[OpenMP 5.0] libomptarget interface for declare mapper functions

[lildmh]

Summary

This patch implements the libomptarget runtime interface for OpenMP 5.0 declare mapper functions. The declare mapper functions generated by Clang will call them to complete the mapping of members.
kmpc_mapper_num_components gets the current number of components for a user-defined mapper; kmpc_push_mapper_component pushes back one component for a user-defined mapper.
The design slides can be found at https://github.com/lingda-li/public-sharing/blob/master/mapper_runtime_design.pptx

[grokos]

I see that target_data pretty much copies the entire code from target_data_begin and target_data_end. That's 200+ duplicate lines of code. Couldn't we just add this check:

// If a valid mapper is attached, call the mapper function to complete the
// mapping of its members.
if (arg_mapper_ptrs && arg_mapper_ptrs[i]) {
  int (*mapper_func_ptr)(int64_t, void *, void *, int64_t, int64_t);
  mapper_func_ptr = (int (*)(int64_t, void *, void *, int64_t, int64_t))(
      arg_mapper_ptrs[i]);
  int rt = (*mapper_func_ptr)(Device.DeviceID, HstPtrBase, HstPtrBegin,
                              data_size, arg_types[i]);
  if (rt != OFFLOAD_SUCCESS) {
    DP("User-defined mapper function failed.\n");
    return OFFLOAD_FAIL;
  }
}

to the existing functions? All that is needed is change the function signature of target_data_begin and target_data_end to include the extra arg_mapper_ptrs argument and set a default value of NULL so that no other changes are needed throughout the code:

target_data_begin(DeviceTy &Device, int32_t arg_num, void **args_base, void **args, int64_t *arg_sizes, int64_t *arg_types, void **arg_mapper_ptrs = NULL);
target_data_end(DeviceTy &Device, int32_t arg_num, void **args_base, void **args, int64_t *arg_sizes, int64_t *arg_types, void **arg_mapper_ptrs = NULL);

After all, I don't see any point in having a function which tries to execute the "begin" code and the "end" code one after the other.

[lildmh]

Hi George,

Thanks for the review.

You are right that target_data is a combination of target_data_begin and target_data_end. They also need to add that code to check if there is a valid mapper. This modification will be in a future patch.

The purpose of this patch is to have an API that is called by the mapper function generated by Clang. In the generated mapper function, it could perform either the functionality of target_data_begin or target_data_end, or a combination of both, depending on the map type. Therefore it's necessary to have target_data, the combination of target_data_begin and target_data_end.

[lildmh]

Implement the new mapper scheme.

[grokos]

I think this patch is wrong. Where are the previous additions of target_data and __tgt_target_data_mapper? Possibly you uploaded the diff between the previous revision and the current one, whereas you need to upload the diff between origin/master and your current HEAD!

[lildmh]

In D60972#1528023, @grokos wrote:

I think this patch is wrong. Where are the previous additions of target_data and __tgt_target_data_mapper? Possibly you uploaded the diff between the previous revision and the current one, whereas you need to upload the diff between origin/master and your current HEAD!

Hi, this is the new scheme, so the previous code is irrelevant now. (no target_data any more)

[lildmh]

In D60972#1528023, @grokos wrote:

I think this patch is wrong. Where are the previous additions of target_data and __tgt_target_data_mapper? Possibly you uploaded the diff between the previous revision and the current one, whereas you need to upload the diff between origin/master and your current HEAD!

Please see the attachment of Ravi sent for the biweekly meeting to see details about this new scheme. Sorry I forgot to mention

[Hahnfeld]

In D60972#1528060, @lildmh wrote:

In D60972#1528023, @grokos wrote:

I think this patch is wrong. Where are the previous additions of target_data and __tgt_target_data_mapper? Possibly you uploaded the diff between the previous revision and the current one, whereas you need to upload the diff between origin/master and your current HEAD!

Please see the attachment of Ravi sent for the biweekly meeting to see details about this new scheme. Sorry I forgot to mention

It would be great to have such things in public...

[lildmh]

In D60972#1528662, @Hahnfeld wrote:

In D60972#1528060, @lildmh wrote:

In D60972#1528023, @grokos wrote:

I think this patch is wrong. Where are the previous additions of target_data and __tgt_target_data_mapper? Possibly you uploaded the diff between the previous revision and the current one, whereas you need to upload the diff between origin/master and your current HEAD!

Please see the attachment of Ravi sent for the biweekly meeting to see details about this new scheme. Sorry I forgot to mention

It would be great to have such things in public...

Sure, there is no secret. Please see it here if you are interested: https://github.com/lingda-li/public-sharing/blob/master/mapper_runtime_design.pptx

[Hahnfeld]

In D60972#1529083, @lildmh wrote:

In D60972#1528662, @Hahnfeld wrote:

It would be great to have such things in public...

Sure, there is no secret. Please see it here if you are interested: https://github.com/lingda-li/public-sharing/blob/master/mapper_runtime_design.pptx

From a quick look, I'd say this does not reflect the current design: The types are named differently, have a different layout (SoA vs AoS) and there's no implementation of __tgt_target_mapper in this patch as @grokos mentioned.
Moreover, I'd question the following things:

1. Why are we back to __kmpc_? naming? Most other functions specific to libomptarget are called __tgt_?.
2. Do you really want to construct std::vectors in the compiler generated code? That's bound to cause trouble with Fortran, isn't it?

[lildmh]

In D60972#1529151, @Hahnfeld wrote:

In D60972#1529083, @lildmh wrote:

In D60972#1528662, @Hahnfeld wrote:

It would be great to have such things in public...

Sure, there is no secret. Please see it here if you are interested: https://github.com/lingda-li/public-sharing/blob/master/mapper_runtime_design.pptx

From a quick look, I'd say this does not reflect the current design: The types are named differently, have a different layout (SoA vs AoS) and there's no implementation of __tgt_target_mapper in this patch as @grokos mentioned.

Hi Jonas, starting from slide 8 is the current design, __tgt_target_mapper etc. are deprecated. It may not accurately reflect the current code but the framework should be the same.

Moreover, I'd question the following things:

1. Why are we back to __kmpc_? naming? Most other functions specific to libomptarget are called __tgt_?.

There are other functions in libomptarget starting with __kmpc_, for example, __kmpc_push_target_tripcount.
My understanding is anything that does not directly call the device starting with __kmpc_. The IBM and Intel compiler people seem to be okay with this naming.

2. Do you really want to construct std::vectors in the compiler generated code? That's bound to cause trouble with Fortran, isn't it?

The compiler doesn't generate code related to std::vector. It's only used in the runtime implementation, so it should be okay with Fortran. Again, the IBM and Intel compiler people seem to agree with it.

[Hahnfeld]

In D60972#1529215, @lildmh wrote:

In D60972#1529151, @Hahnfeld wrote:

In D60972#1529083, @lildmh wrote:

In D60972#1528662, @Hahnfeld wrote:

It would be great to have such things in public...

Sure, there is no secret. Please see it here if you are interested: https://github.com/lingda-li/public-sharing/blob/master/mapper_runtime_design.pptx

From a quick look, I'd say this does not reflect the current design: The types are named differently, have a different layout (SoA vs AoS) and there's no implementation of __tgt_target_mapper in this patch as @grokos mentioned.

Hi Jonas, starting from slide 8 is the current design, __tgt_target_mapper etc. are deprecated. It may not accurately reflect the current code but the framework should be the same.

Moreover, I'd question the following things:

1. Why are we back to __kmpc_? naming? Most other functions specific to libomptarget are called __tgt_?.

There are other functions in libomptarget starting with __kmpc_, for example, __kmpc_push_target_tripcount.
My understanding is anything that does not directly call the device starting with __kmpc_. The IBM and Intel compiler people seem to be okay with this naming.

Yes, this is the only function AFAICS and it has a comment "will be revised". All other functions related to mapping start with __tgt so unless there is good incentive, we should follow this naming convention.

2. Do you really want to construct std::vectors in the compiler generated code? That's bound to cause trouble with Fortran, isn't it?

The compiler doesn't generate code related to std::vector. It's only used in the runtime implementation, so it should be okay with Fortran. Again, the IBM and Intel compiler people seem to agree with it.

Maybe I don't understand where rt_mapper_handle comes from. According to the design slides and D59474, it passed as an argument to the generated omp_mapper[...] function, but how is the runtime system involved in its creation? Will there be additional interface functions / changes that will call this?

[lildmh]

In D60972#1529238, @Hahnfeld wrote:

In D60972#1529215, @lildmh wrote:

In D60972#1529151, @Hahnfeld wrote:

In D60972#1529083, @lildmh wrote:

In D60972#1528662, @Hahnfeld wrote:

It would be great to have such things in public...

Sure, there is no secret. Please see it here if you are interested: https://github.com/lingda-li/public-sharing/blob/master/mapper_runtime_design.pptx

From a quick look, I'd say this does not reflect the current design: The types are named differently, have a different layout (SoA vs AoS) and there's no implementation of __tgt_target_mapper in this patch as @grokos mentioned.

Hi Jonas, starting from slide 8 is the current design, __tgt_target_mapper etc. are deprecated. It may not accurately reflect the current code but the framework should be the same.

Moreover, I'd question the following things:

1. Why are we back to __kmpc_? naming? Most other functions specific to libomptarget are called __tgt_?.

There are other functions in libomptarget starting with __kmpc_, for example, __kmpc_push_target_tripcount.
My understanding is anything that does not directly call the device starting with __kmpc_. The IBM and Intel compiler people seem to be okay with this naming.

Yes, this is the only function AFAICS and it has a comment "will be revised". All other functions related to mapping start with __tgt so unless there is good incentive, we should follow this naming convention.

Sure, I do prefer __tgt, as long as everyone else is okay with it.

2. Do you really want to construct std::vectors in the compiler generated code? That's bound to cause trouble with Fortran, isn't it?

The compiler doesn't generate code related to std::vector. It's only used in the runtime implementation, so it should be okay with Fortran. Again, the IBM and Intel compiler people seem to agree with it.

Maybe I don't understand where rt_mapper_handle comes from. According to the design slides and D59474, it passed as an argument to the generated omp_mapper[...] function, but how is the runtime system involved in its creation? Will there be additional interface functions / changes that will call this?

The idea is the runtime will create a MapperComponentsTy (std::vector) before calling the mapper function, in, for instance, __tgt_target_data_begin (These parts will be implemented in later patches). When the mapper function is called, the pointer of MapperComponentsTy is passed to it, as void *rt_mapper_handle. The mapper function will call __kmpc_push_mapper_component using this rt_mapper_handle, and then the runtime can put it into the MapperComponentsTy

[grokos]

In D60972#1529265, @lildmh wrote:

In D60972#1529238, @Hahnfeld wrote:

In D60972#1529215, @lildmh wrote:

In D60972#1529151, @Hahnfeld wrote:

Moreover, I'd question the following things:

1. Why are we back to __kmpc_? naming? Most other functions specific to libomptarget are called __tgt_?.

There are other functions in libomptarget starting with __kmpc_, for example, __kmpc_push_target_tripcount.
My understanding is anything that does not directly call the device starting with __kmpc_. The IBM and Intel compiler people seem to be okay with this naming.

Yes, this is the only function AFAICS and it has a comment "will be revised". All other functions related to mapping start with __tgt so unless there is good incentive, we should follow this naming convention.

Sure, I do prefer __tgt, as long as everyone else is okay with it.

Yes, please use a name that starts with __tgt. Names starting with __kmpc are meant for the libomp host runtime specifically. __kmpc_push_tripcount was implemented in libomptarget in a rush and the implementation is incorrect, it will be transferred to libomp and re-implemented correctly.

[Hahnfeld]

In D60972#1529265, @lildmh wrote:

In D60972#1529238, @Hahnfeld wrote:

In D60972#1529215, @lildmh wrote:

The compiler doesn't generate code related to std::vector. It's only used in the runtime implementation, so it should be okay with Fortran. Again, the IBM and Intel compiler people seem to agree with it.

Maybe I don't understand where rt_mapper_handle comes from. According to the design slides and D59474, it passed as an argument to the generated omp_mapper[...] function, but how is the runtime system involved in its creation? Will there be additional interface functions / changes that will call this?

The idea is the runtime will create a MapperComponentsTy (std::vector) before calling the mapper function, in, for instance, __tgt_target_data_begin (These parts will be implemented in later patches). When the mapper function is called, the pointer of MapperComponentsTy is passed to it, as void *rt_mapper_handle. The mapper function will call __kmpc_push_mapper_component using this rt_mapper_handle, and then the runtime can put it into the MapperComponentsTy

That's hard to guess from the current patch and isn't in the design slides either (or I have overlooked it). Such information should be made available to reviewers such that they can assess the implementation!

If the new functions mapper_num_components and push_mapper_component are only used by a "callback" that is called from the runtime, why do we need to export them? We could pass the function pointers next to rt_mapper_handle and be done with it.

[lildmh]

In D60972#1530490, @Hahnfeld wrote:

In D60972#1529265, @lildmh wrote:

In D60972#1529238, @Hahnfeld wrote:

In D60972#1529215, @lildmh wrote:

The compiler doesn't generate code related to std::vector. It's only used in the runtime implementation, so it should be okay with Fortran. Again, the IBM and Intel compiler people seem to agree with it.

Maybe I don't understand where rt_mapper_handle comes from. According to the design slides and D59474, it passed as an argument to the generated omp_mapper[...] function, but how is the runtime system involved in its creation? Will there be additional interface functions / changes that will call this?

The idea is the runtime will create a MapperComponentsTy (std::vector) before calling the mapper function, in, for instance, __tgt_target_data_begin (These parts will be implemented in later patches). When the mapper function is called, the pointer of MapperComponentsTy is passed to it, as void *rt_mapper_handle. The mapper function will call __kmpc_push_mapper_component using this rt_mapper_handle, and then the runtime can put it into the MapperComponentsTy

That's hard to guess from the current patch and isn't in the design slides either (or I have overlooked it). Such information should be made available to reviewers such that they can assess the implementation!

Sorry for the inconvenience. I was assuming the reviewer is in the biweekly OpenMP Clang meeting where this scheme is discussed extensively. If you are interested, I can ask Ravi to add you to the mailing list.

If the new functions mapper_num_components and push_mapper_component are only used by a "callback" that is called from the runtime, why do we need to export them? We could pass the function pointers next to rt_mapper_handle and be done with it.

That sounds reasonable to have them function pointers, although I am not sure why it is better than exporting these functions. I present this idea to others in that meeting today, and let's see how they like it.

[lildmh]

Use tgt instead of kmpc

[lildmh]

@Hahnfeld Do you really think it is necessary to pass these two functions as arguments, instead of exporting them. If you do, could you explain why?

Thanks,
Lingda Li

[Hahnfeld]

In D60972#1533013, @lildmh wrote:

@Hahnfeld Do you really think it is necessary to pass these two functions as arguments, instead of exporting them. If you do, could you explain why?

I don't say it's necessary, but rather an option. Asked differently, why do we need to export them (and decide on externally visible names) if they're only used in a function where we can pass them as arguments?

At the moment, this patch doesn't really add any value (meaning changed behavior) to the runtime. It's needed for D59474 which is already large enough on its own, but it doesn't get to any state where it can be used.

[lildmh]

In D60972#1536070, @Hahnfeld wrote:

In D60972#1533013, @lildmh wrote:

@Hahnfeld Do you really think it is necessary to pass these two functions as arguments, instead of exporting them. If you do, could you explain why?

I don't say it's necessary, but rather an option. Asked differently, why do we need to export them (and decide on externally visible names) if they're only used in a function where we can pass them as arguments?

At the moment, this patch doesn't really add any value (meaning changed behavior) to the runtime. It's needed for D59474 which is already large enough on its own, but it doesn't get to any state where it can be used.

I don't have a strong reason to export it either. One reason is it avoids one indirect memory access so could be potentially better for performance (the difference should be very minor).

Yea I agree this patch doesn't really do anything itself, it just provide a runtime interface for D59474. Please let me know if there is anything that prevents this patch from being accepted.

[lildmh]

Ping and rebase

[grokos]

Now that the clang-side patch is finalized, this is almost good to go. What is missing from this patch is a test. Can you add something under libomptarget/test/offloading/?

[lildmh]

In D60972#1605188, @grokos wrote:

Now that the clang-side patch is finalized, this is almost good to go. What is missing from this patch is a test. Can you add something under libomptarget/test/offloading/?

Sure, since this is very simple I'll add a simple test. Do you think the test should be in libomptarget/test/offloading/ or libomptarget/test/api/?

[grokos]

In D60972#1605210, @lildmh wrote:

In D60972#1605188, @grokos wrote:

Now that the clang-side patch is finalized, this is almost good to go. What is missing from this patch is a test. Can you add something under libomptarget/test/offloading/?

Sure, since this is very simple I'll add a simple test. Do you think the test should be in libomptarget/test/offloading/ or libomptarget/test/api/?

Sorry, I meant libomptarget/test/mapping/!

The api directory is meant for test cases calling omp_* API functions, which is not the case here.

[lildmh]

In D60972#1605250, @grokos wrote:

In D60972#1605210, @lildmh wrote:

In D60972#1605188, @grokos wrote:

Now that the clang-side patch is finalized, this is almost good to go. What is missing from this patch is a test. Can you add something under libomptarget/test/offloading/?

Sure, since this is very simple I'll add a simple test. Do you think the test should be in libomptarget/test/offloading/ or libomptarget/test/api/?

Sorry, I meant libomptarget/test/mapping/!

The api directory is meant for test cases calling omp_* API functions, which is not the case here.

Since the mapper is not really implemented in this patch, if I add a test, it will be something like below:

__tgt_push_mapper_component(h, base0, begin0, size0, type0);
__tgt_push_mapper_component(h, base1, begin1, size1, type1);
auto total_size = __tgt_mapper_num_components(h);
printf("size=%d", total_size);
// CHECK: size=2

It seems to me this test is not meaningful. I can add a more meaningful test after all mapper patches are upstreamed.
Do you think we need a meaningless test like this now?

[grokos]

In D60972#1606804, @lildmh wrote:

Since the mapper is not really implemented in this patch, if I add a test, it will be something like below:

__tgt_push_mapper_component(h, base0, begin0, size0, type0);
__tgt_push_mapper_component(h, base1, begin1, size1, type1);
auto total_size = __tgt_mapper_num_components(h);
printf("size=%d", total_size);
// CHECK: size=2

It seems to me this test is not meaningful. I can add a more meaningful test after all mapper patches are upstreamed.
Do you think we need a meaningless test like this now?

Yes, it's good to have a test, even a very elementary one. When full support for declare mapper is upstreamed we can revisit the test and extend it to check real-use scenarios.

[lildmh]

In D60972#1606990, @grokos wrote:

In D60972#1606804, @lildmh wrote:

Since the mapper is not really implemented in this patch, if I add a test, it will be something like below:

__tgt_push_mapper_component(h, base0, begin0, size0, type0);
__tgt_push_mapper_component(h, base1, begin1, size1, type1);
auto total_size = __tgt_mapper_num_components(h);
printf("size=%d", total_size);
// CHECK: size=2

It seems to me this test is not meaningful. I can add a more meaningful test after all mapper patches are upstreamed.
Do you think we need a meaningless test like this now?

Yes, it's good to have a test, even a very elementary one. When full support for declare mapper is upstreamed we can revisit the test and extend it to check real-use scenarios.

I just realized that these functions (__tgt_push_mapper_component and __tgt_mapper_num_components) are not exposed to users (i.e., defined in omp.h), so the test proposed above is not possible.

I cannot imagine what test it can have for this patch now, so I think we can leave this patch testless. If you have an idea of test, please let me know.

[Hahnfeld]

In D60972#1607088, @lildmh wrote:

In D60972#1606990, @grokos wrote:

In D60972#1606804, @lildmh wrote:

Since the mapper is not really implemented in this patch, if I add a test, it will be something like below:

__tgt_push_mapper_component(h, base0, begin0, size0, type0);
__tgt_push_mapper_component(h, base1, begin1, size1, type1);
auto total_size = __tgt_mapper_num_components(h);
printf("size=%d", total_size);
// CHECK: size=2

It seems to me this test is not meaningful. I can add a more meaningful test after all mapper patches are upstreamed.
Do you think we need a meaningless test like this now?

Yes, it's good to have a test, even a very elementary one. When full support for declare mapper is upstreamed we can revisit the test and extend it to check real-use scenarios.

I just realized that these functions (__tgt_push_mapper_component and __tgt_mapper_num_components) are not exposed to users (i.e., defined in omp.h), so the test proposed above is not possible.

I cannot imagine what test it can have for this patch now, so I think we can leave this patch testless. If you have an idea of test, please let me know.

You need to declare them yourself in the test. That's not really elegant, but many other runtime tests already do.

[lildmh]

In D60972#1607108, @Hahnfeld wrote:

You need to declare them yourself in the test. That's not really elegant, but many other runtime tests already do.

Thanks for the tip! I can do that. Since I'm pretty new to the runtime, could you suggest a similar test that I should look into?

[Hahnfeld]

In D60972#1607134, @lildmh wrote:

In D60972#1607108, @Hahnfeld wrote:

You need to declare them yourself in the test. That's not really elegant, but many other runtime tests already do.

Thanks for the tip! I can do that. Since I'm pretty new to the runtime, could you suggest a similar test that I should look into?

test/offloading/requires.c does so: https://github.com/llvm/llvm-project/blob/master/openmp/libomptarget/test/offloading/requires.c#L20

I think that's the only one for libomptarget right now, but the host runtime has more complex ones, for example https://github.com/llvm/llvm-project/blob/master/openmp/runtime/test/tasking/kmp_taskloop.c

[lildmh]

Add a test

[grokos]

OK, it's good to go now.

[lildmh]

@Meinersbur Hi Michael, could you help me commit this patch? Thanks!

libomptarget/src/exports

 VERS1.0 {
   global:
     __tgt_register_requires;
     __tgt_register_lib;
     __tgt_unregister_lib;
     __tgt_target_data_begin;
     __tgt_target_data_end;
     __tgt_target_data_update;
     __tgt_target;
     __tgt_target_teams;
     __tgt_target_data_begin_nowait;
     __tgt_target_data_end_nowait;
     __tgt_target_data_update_nowait;
     __tgt_target_nowait;
     __tgt_target_teams_nowait;
+    __tgt_mapper_num_components;
+    __tgt_push_mapper_component;
     omp_get_num_devices;
     omp_get_initial_device;
     omp_target_alloc;
     omp_target_free;
     omp_target_is_present;
     omp_target_memcpy;
     omp_target_memcpy_rect;
     omp_target_associate_ptr;
     omp_target_disassociate_ptr;
     __kmpc_push_target_tripcount;
   local:
     *;
 };
 

libomptarget/src/interface.cpp

EXTERN int __tgt_target_teams_nowait(int64_t device_id, void *host_ptr,
     void *depList, int32_t noAliasDepNum, void *noAliasDepList) {
   if (depNum + noAliasDepNum > 0)
     __kmpc_omp_taskwait(NULL, __kmpc_global_thread_num(NULL));
 
   return __tgt_target_teams(device_id, host_ptr, arg_num, args_base, args,
                             arg_sizes, arg_types, team_num, thread_limit);
 }
 
+// Get the current number of components for a user-defined mapper.
+EXTERN int64_t __tgt_mapper_num_components(void *rt_mapper_handle) {
+  auto *MapperComponentsPtr = (struct MapperComponentsTy *)rt_mapper_handle;
+  int64_t size = MapperComponentsPtr->Components.size();
+  DP("__tgt_mapper_num_components(Handle=" DPxMOD ") returns %" PRId64 "\n",
+     DPxPTR(rt_mapper_handle), size);
+  return size;
+}
+
+// Push back one component for a user-defined mapper.
+EXTERN void __tgt_push_mapper_component(void *rt_mapper_handle, void *base,
+                                        void *begin, int64_t size,
+                                        int64_t type) {
+  DP("__tgt_push_mapper_component(Handle=" DPxMOD
+     ") adds an entry (Base=" DPxMOD ", Begin=" DPxMOD ", Size=%" PRId64
+     ", Type=0x%" PRIx64 ").\n",
+     DPxPTR(rt_mapper_handle), DPxPTR(base), DPxPTR(begin), size, type);
+  auto *MapperComponentsPtr = (struct MapperComponentsTy *)rt_mapper_handle;
+  MapperComponentsPtr->Components.push_back(
+      MapComponentInfoTy(base, begin, size, type));
+}
+
 EXTERN void __kmpc_push_target_tripcount(int64_t device_id,
     uint64_t loop_tripcount) {
   if (IsOffloadDisabled())
     return;
 
   if (device_id == OFFLOAD_DEVICE_DEFAULT) {
     device_id = omp_get_default_device();
   }

libomptarget/src/private.h

 enum kmp_target_offload_kind {
   tgt_disabled = 0,
   tgt_default = 1,
   tgt_mandatory = 2
 };
 typedef enum kmp_target_offload_kind kmp_target_offload_kind_t;
 extern kmp_target_offload_kind_t TargetOffloadPolicy;
 
+// This structure stores information of a mapped memory region.
+struct MapComponentInfoTy {
+  void *Base;
+  void *Begin;
+  int64_t Size;
+  int64_t Type;
+  MapComponentInfoTy() = default;
+  MapComponentInfoTy(void *Base, void *Begin, int64_t Size, int64_t Type)
+      : Base(Base), Begin(Begin), Size(Size), Type(Type) {}
+};
+
+// This structure stores all components of a user-defined mapper. The number of
+// components are dynamically decided, so we utilize C++ STL vector
+// implementation here.
+struct MapperComponentsTy {
+  std::vector<MapComponentInfoTy> Components;
+};
+
 ////////////////////////////////////////////////////////////////////////////////
 // implemtation for fatal messages
 ////////////////////////////////////////////////////////////////////////////////
 
 #define FATAL_MESSAGE0(_num, _str)                                    \
   do {                                                                \
     fprintf(stderr, "Libomptarget fatal error %d: %s\n", _num, _str); \
     exit(1);                                                          \

libomptarget/test/mapping/declare_mapper_api.cpp

+// RUN: %libomptarget-compile-run-and-check-aarch64-unknown-linux-gnu
+// RUN: %libomptarget-compile-run-and-check-powerpc64-ibm-linux-gnu
+// RUN: %libomptarget-compile-run-and-check-powerpc64le-ibm-linux-gnu
+// RUN: %libomptarget-compile-run-and-check-x86_64-pc-linux-gnu
+
+#include <cstdio>
+#include <cstdlib>
+
+// Data structure definitions copied from OpenMP RTL.
+struct MapComponentInfoTy {
+  void *Base;
+  void *Begin;
+  int64_t Size;
+  int64_t Type;
+  MapComponentInfoTy() = default;
+  MapComponentInfoTy(void *Base, void *Begin, int64_t Size, int64_t Type)
+      : Base(Base), Begin(Begin), Size(Size), Type(Type) {}
+};
+
+struct MapperComponentsTy {
+  std::vector<MapComponentInfoTy> Components;
+};
+
+// OpenMP RTL interfaces
+#ifdef __cplusplus
+extern "C" {
+#endif
+int64_t __tgt_mapper_num_components(void *rt_mapper_handle);
+void __tgt_push_mapper_component(void *rt_mapper_handle, void *base,
+                                 void *begin, int64_t size, int64_t type);
+#ifdef __cplusplus
+}
+#endif
+
+int main(int argc, char *argv[]) {
+  MapperComponentsTy MC;
+  void *base, *begin;
+  int64_t size, type;
+  // Push 2 elements into MC.
+  __tgt_push_mapper_component((void *)&MC, base, begin, size, type);
+  __tgt_push_mapper_component((void *)&MC, base, begin, size, type);
+  int64_t num = __tgt_mapper_num_components((void *)&MC);
+  // CHECK: num=2
+  printf("num=%lld\n", num);
+  return 0;
+}