1 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
2 /*
3 * Copyright (c) 2014 Mellanox Technologies, Inc.
4 * All rights reserved.
5 * Copyright (c) 2015 Los Alamos National Security, LLC. All rights
6 * reserved.
7 * $COPYRIGHT$
8 *
9 * Additional copyrights may follow
10 *
11 * $HEADER$
12 */
13
14 /**
15 * @file
16 *
17 * sshmem (shared memory backing facility) framework component interface
18 * definitions.
19 *
20 * The module has the following functions:
21 *
22 * - module_init
23 * - segment_create
24 * - segment_attach
25 * - segment_detach
26 * - unlink
27 * - module_finalize
28 */
29
30 #ifndef MCA_SSHMEM_H
31 #define MCA_SSHMEM_H
32
33 #include "oshmem_config.h"
34 #include "oshmem/types.h"
35 #include "oshmem/constants.h"
36
37 #include "oshmem/mca/mca.h"
38 #include "opal/mca/base/base.h"
39
40 #include "oshmem/mca/sshmem/sshmem_types.h"
41
42 BEGIN_C_DECLS
43
44 /* ////////////////////////////////////////////////////////////////////////// */
45 typedef int
46 (*mca_sshmem_base_component_runtime_query_fn_t)(mca_base_module_t **module,
47 int *priority,
48 const char *hint);
49
50 /* structure for sshmem components. */
51 struct mca_sshmem_base_component_2_0_0_t {
52 /* base MCA component */
53 mca_base_component_t base_version;
54 /* base MCA data */
55 mca_base_component_data_t base_data;
56 /* component runtime query */
57 mca_sshmem_base_component_runtime_query_fn_t runtime_query;
58 };
59
60 /* convenience typedefs */
61 typedef struct mca_sshmem_base_component_2_0_0_t
62 mca_sshmem_base_component_2_0_0_t;
63
64 typedef struct mca_sshmem_base_component_2_0_0_t mca_sshmem_base_component_t;
65
66 /* ////////////////////////////////////////////////////////////////////////// */
67 /* shmem API function pointers */
68
69 /**
70 * module initialization function.
71 * @return OSHMEM_SUCCESS on success.
72 */
73 typedef int
74 (*mca_sshmem_base_module_init_fn_t)(void);
75
76 /**
77 * create a new shared memory segment and initialize members in structure
78 * pointed to by ds_buf.
79 *
80 * @param ds_buf pointer to map_segment_t typedef'd structure
81 * defined in shmem_types.h (OUT).
82 *
83 * @param file_name file_name unique string identifier that must be a valid,
84 * writable path (IN).
85 *
86 * @param address address to attach the segment at, or 0 allocate
87 * any available address in the process.
88 *
89 * @param size size of the shared memory segment.
90 *
91 * @param hint hint of the shared memory segment.
92 *
93 * @return OSHMEM_SUCCESS on success.
94 */
95 typedef int
96 (*mca_sshmem_base_module_segment_create_fn_t)(map_segment_t *ds_buf,
97 const char *file_name,
98 size_t size, long hint);
99
100 /**
101 * attach to an existing shared memory segment initialized by segment_create.
102 *
103 * @param ds_buf pointer to initialized map_segment_t typedef'd
104 * structure (IN/OUT).
105 *
106 * @return base address of shared memory segment on success. returns
107 * NULL otherwise.
108 */
109 typedef void *
110 (*mca_sshmem_base_module_segment_attach_fn_t)(map_segment_t *ds_buf, sshmem_mkey_t *mkey);
111
112 /**
113 * detach from an existing shared memory segment.
114 *
115 * @param ds_buf pointer to initialized map_segment_t typedef'd structure
116 * (IN/OUT).
117 *
118 * @return OSHMEM_SUCCESS on success.
119 */
120 typedef int
121 (*mca_sshmem_base_module_segment_detach_fn_t)(map_segment_t *ds_buf, sshmem_mkey_t *mkey);
122
123 /**
124 * unlink an existing shared memory segment.
125 *
126 * @param ds_buf pointer to initialized map_segment_t typedef'd structure
127 * (IN/OUT).
128 *
129 * @return OSHMEM_SUCCESS on success.
130 */
131 typedef int
132 (*mca_sshmem_base_module_unlink_fn_t)(map_segment_t *ds_buf);
133
134 /**
135 * module finalize function. invoked by the base on the selected
136 * module when the sshmem framework is being shut down.
137 */
138 typedef int (*mca_sshmem_base_module_finalize_fn_t)(void);
139
140 /**
141 * structure for shmem modules
142 */
143 struct mca_sshmem_base_module_2_0_0_t {
144 mca_sshmem_base_module_init_fn_t module_init;
145 mca_sshmem_base_module_segment_create_fn_t segment_create;
146 mca_sshmem_base_module_segment_attach_fn_t segment_attach;
147 mca_sshmem_base_module_segment_detach_fn_t segment_detach;
148 mca_sshmem_base_module_unlink_fn_t unlink;
149 mca_sshmem_base_module_finalize_fn_t module_finalize;
150 };
151
152 /**
153 * convenience typedefs
154 */
155 typedef struct mca_sshmem_base_module_2_0_0_t mca_sshmem_base_module_2_0_0_t;
156 typedef struct mca_sshmem_base_module_2_0_0_t mca_sshmem_base_module_t;
157
158 /**
159 * macro for use in components that are of type sshmem
160 * see: oshmem/mca/mca.h for more information
161 */
162 #define MCA_SSHMEM_BASE_VERSION_2_0_0 \
163 OSHMEM_MCA_BASE_VERSION_2_1_0("sshmem", 2, 0, 0)
164
165 END_C_DECLS
166
167 #endif /* MCA_SSHMEM_H */