1// vim:set ft=cpp: -*- Mode: C++ -*-
2/**
3 * \file
4 * Unique_cap / Unique_del_cap
5 */
6/*
7 * (c) 2017 Alexander Warg <alexander.warg@kernkonzept.com>
8 *
9 * This file is part of TUD:OS and distributed under the terms of the
10 * GNU General Public License 2.
11 * Please see the COPYING-GPL-2 file for details.
12 *
13 * As a special exception, you may use this file as part of a free software
14 * library without restriction.  Specifically, if other files instantiate
15 * templates or use macros or inline functions from this file, or you compile
16 * this file and link it with other files to produce an executable, this
17 * file does not by itself cause the resulting executable to be covered by
18 * the GNU General Public License.  This exception does not however
19 * invalidate any other reasons why the executable file might be covered by
20 * the GNU General Public License.
21 */
22
23#pragma once
24
25#include <l4/re/util/cap_alloc>
26#include <l4/sys/cxx/smart_capability_1x>
27
28namespace L4Re { namespace Util {
29
30/**
31 * Unique capability that implements automatic free and unmap of the
32 * capability selector.
33 *
34 * \tparam T  Type of the object the capability refers to.
35 *
36 * The ownership of the capability is managed in the same way as unique_ptr.
37 *
38 * Usage:
39 *
40 *     {
41 *       L4Re::Util::Unique_cap<L4Re::Dataspace>
42 *         ds_cap = L4Re::Util::make_unique_cap<L4Re::Dataspace>();
43 *
44 *       // use the dataspace cap
45 *       L4Re::chksys(mem_alloc->alloc(L4_PAGESIZE, ds_cap.get()));
46 *
47 *       ...
48 *
49 *       // At the end of the scope ds_cap is unmapped and the capability
50 *       // selector is freed.
51 *     }
52 */
53template< typename T >
54using Unique_cap = L4::Detail::Unique_cap_impl<T, Smart_cap_auto<L4_FP_ALL_SPACES>>;
55/// \copydoc Unique_cap
56template< typename T >
57using unique_cap = L4::Detail::Unique_cap_impl<T, Smart_cap_auto<L4_FP_ALL_SPACES>>;
58
59/**
60 * Allocate a capability slot and wrap it in an Unique_cap.
61 *
62 * \tparam T  Type of the object the capability refers to.
63 */
64template< typename T >
65Unique_cap<T>
66make_unique_cap()
67{ return Unique_cap<T>(cap_alloc.alloc<T>()); }
68
69/**
70 * Unique capability that implements automatic free and unmap+delete of the
71 * capability selector.
72 *
73 * \tparam T  Type of the object the capability refers to.
74 *
75 * The main difference to Unique_cap is that the unmap is done with the
76 * deletion flag enabled and this leads to the deletion of the object
77 * if the current task holds appropriate deletion rights.
78 *
79 * Usage:
80 *
81 *     {
82 *       L4Re::Util::Unique_del_cap<L4Re::Dataspace>
83 *         ds_cap = make_unique_del_cap<L4Re::Dataspace>());
84 *
85 *       // use the dataspace cap
86 *       L4Re::chksys(mem_alloc->alloc(L4_PAGESIZE, ds_cap.get()));
87 *
88 *       ...
89 *
90 *       // At the end of the scope ds_cap is unmapped and the capability
91 *       // selector is freed. Because the deletion flag is set the data space
92 *       // shall also be deleted (even if there are other references to this
93 *       // data space).
94 *     }
95 */
96template< typename T >
97using Unique_del_cap = L4::Detail::Unique_cap_impl<T, Smart_cap_auto<L4_FP_DELETE_OBJ>>;
98template< typename T >
99/// \copydoc Unique_del_cap
100using unique_del_cap = L4::Detail::Unique_cap_impl<T, Smart_cap_auto<L4_FP_DELETE_OBJ>>;
101
102/**
103 * Allocate a capability slot and wrap it in an Unique_del_cap.
104 *
105 * \tparam T  Type of the object the capability refers to.
106 */
107template< typename T >
108Unique_del_cap<T>
109make_unique_del_cap()
110{ return Unique_del_cap<T>(cap_alloc.alloc<T>()); }
111
112}}
113
114