1 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
2 /*
3 * Copyright (c) 2004-2008 The Trustees of Indiana University and Indiana
4 * University Research and Technology
5 * Corporation. All rights reserved.
6 * Copyright (c) 2004-2005 The University of Tennessee and The University
7 * of Tennessee Research Foundation. All rights
8 * reserved.
9 * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
10 * University of Stuttgart. All rights reserved.
11 * Copyright (c) 2004-2005 The Regents of the University of California.
12 * All rights reserved.
13 * Copyright (c) 2007-2015 Cisco Systems, Inc. All rights reserved.
14 * Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.
15 * Copyright (c) 2010 IBM Corporation. All rights reserved.
16 * Copyright (c) 2010-2015 Los Alamos National Security, LLC.
17 * All rights reserved.
18 * $COPYRIGHT$
19 *
20 * Additional copyrights may follow
21 *
22 * $HEADER$
23 */
24
25 /**
26 * @file
27 *
28 * shmem (shared memory backing facility) framework component interface
29 * definitions.
30 *
31 * usage example: see ompi/mca/common/sm
32 *
33 * The module has the following functions:
34 *
35 * - module_init
36 * - segment_create
37 * - ds_copy
38 * - segment_attach
39 * - segment_detach
40 * - unlink
41 * - module_finalize
42 */
43
44 #ifndef OPAL_SHMEM_H
45 #define OPAL_SHMEM_H
46
47 #include "opal_config.h"
48
49 #include "opal/mca/mca.h"
50 #include "opal/mca/base/base.h"
51
52 #include "opal/mca/shmem/shmem_types.h"
53
54 BEGIN_C_DECLS
55
56 /* ////////////////////////////////////////////////////////////////////////// */
57 typedef int
58 (*mca_shmem_base_component_runtime_query_fn_t)(mca_base_module_t **module,
59 int *priority,
60 const char *hint);
61
62 /* structure for shmem components. */
63 struct opal_shmem_base_component_2_0_0_t {
64 /* base MCA component */
65 mca_base_component_t base_version;
66 /* base MCA data */
67 mca_base_component_data_t base_data;
68 /* component runtime query */
69 mca_shmem_base_component_runtime_query_fn_t runtime_query;
70 };
71
72 /* convenience typedefs */
73 typedef struct opal_shmem_base_component_2_0_0_t
74 opal_shmem_base_component_2_0_0_t;
75
76 typedef struct opal_shmem_base_component_2_0_0_t opal_shmem_base_component_t;
77
78 /* ////////////////////////////////////////////////////////////////////////// */
79 /* shmem API function pointers */
80
81 /**
82 * module initialization function.
83 * @return OPAL_SUCCESS on success.
84 */
85 typedef int
86 (*opal_shmem_base_module_init_fn_t)(void);
87
88 /**
89 * copy shmem data structure information pointed to by from to the structure
90 * pointed to by to.
91 *
92 * @param from source pointer (IN).
93 *
94 * @param to destination pointer (OUT).
95 *
96 * @return OPAL_SUCCESS on success.
97 */
98 typedef int
99 (*opal_shmem_base_ds_copy_fn_t)(const opal_shmem_ds_t *from,
100 opal_shmem_ds_t *to);
101
102 /**
103 * create a new shared memory segment and initialize members in structure
104 * pointed to by ds_buf.
105 *
106 * @param ds_buf pointer to opal_shmem_ds_t typedef'd structure
107 * defined in shmem_types.h (OUT).
108 *
109 * @param file_name file_name unique string identifier that must be a valid,
110 * writable path (IN).
111 *
112 * @param size size of the shared memory segment.
113 *
114 * @return OPAL_SUCCESS on success.
115 */
116 typedef int
117 (*opal_shmem_base_module_segment_create_fn_t)(opal_shmem_ds_t *ds_buf,
118 const char *file_name,
119 size_t size);
120
121 /**
122 * attach to an existing shared memory segment initialized by segment_create.
123 *
124 * @param ds_buf pointer to initialized opal_shmem_ds_t typedef'd
125 * structure (IN/OUT).
126 *
127 * @return base address of shared memory segment on success. returns
128 * NULL otherwise.
129 */
130 typedef void *
131 (*opal_shmem_base_module_segment_attach_fn_t)(opal_shmem_ds_t *ds_buf);
132
133 /**
134 * detach from an existing shared memory segment.
135 *
136 * @param ds_buf pointer to initialized opal_shmem_ds_t typedef'd structure
137 * (IN/OUT).
138 *
139 * @return OPAL_SUCCESS on success.
140 */
141 typedef int
142 (*opal_shmem_base_module_segment_detach_fn_t)(opal_shmem_ds_t *ds_buf);
143
144 /**
145 * unlink an existing shared memory segment.
146 *
147 * @param ds_buf pointer to initialized opal_shmem_ds_t typedef'd structure
148 * (IN/OUT).
149 *
150 * @return OPAL_SUCCESS on success.
151 */
152 typedef int
153 (*opal_shmem_base_module_unlink_fn_t)(opal_shmem_ds_t *ds_buf);
154
155 /**
156 * module finalize function. invoked by the base on the selected
157 * module when the shmem framework is being shut down.
158 */
159 typedef int (*opal_shmem_base_module_finalize_fn_t)(void);
160
161 /**
162 * structure for shmem modules
163 */
164 struct opal_shmem_base_module_2_0_0_t {
165 mca_base_module_t base;
166 opal_shmem_base_module_init_fn_t module_init;
167 opal_shmem_base_module_segment_create_fn_t segment_create;
168 opal_shmem_base_ds_copy_fn_t ds_copy;
169 opal_shmem_base_module_segment_attach_fn_t segment_attach;
170 opal_shmem_base_module_segment_detach_fn_t segment_detach;
171 opal_shmem_base_module_unlink_fn_t unlink;
172 opal_shmem_base_module_finalize_fn_t module_finalize;
173 };
174
175 /**
176 * convenience typedefs
177 */
178 typedef struct opal_shmem_base_module_2_0_0_t opal_shmem_base_module_2_0_0_t;
179 typedef struct opal_shmem_base_module_2_0_0_t opal_shmem_base_module_t;
180
181 /**
182 * macro for use in components that are of type shmem
183 * see: opal/mca/mca.h for more information
184 */
185 #define OPAL_SHMEM_BASE_VERSION_2_0_0 \
186 OPAL_MCA_BASE_VERSION_2_1_0("shmem", 2, 0, 0)
187
188 END_C_DECLS
189
190 #endif /* OPAL_SHMEM_H */