L4Re - L4 Runtime Environment
kobject
1 // vi:set ft=cpp: -*- Mode: C++ -*-
2 /* \file
3  * Kobject C++ interface.
4  */
5 /*
6  * Copyright (C) 2015 Kernkonzept GmbH.
7  * Author(s): Alexander Warg <alexander.warg@kernkonzept.com>
8  *
9  * This file is distributed under the terms of the GNU General Public
10  * License, version 2. Please see the COPYING-GPL-2 file for details.
11  *
12  * As a special exception, you may use this file as part of a free software
13  * library without restriction. Specifically, if other files instantiate
14  * templates or use macros or inline functions from this file, or you compile
15  * this file and link it with other files to produce an executable, this
16  * file does not by itself cause the resulting executable to be covered by
17  * the GNU General Public License. This exception does not however
18  * invalidate any other reasons why the executable file might be covered by
19  * the GNU General Public License.
20  */
21 #pragma once
22 
23 #include "kernel_object.h"
24 #include "types.h"
25 #include "__typeinfo.h"
26 
27 namespace L4 {
28 
29 /**
30  * \ingroup l4_kernel_object_api
31  * Base class for all kinds of kernel objects and remote objects, referenced by
32  * capabilities.
33  *
34  * \includefile{l4/sys/capability}
35  *
36  * This is the base class for all remote objects accessible using RPC.
37  * However, subclasses doe not directly inherit from L4::Kobject but _must_
38  * use L4::Kobject_t (L4::Kobject_0t, L4::Kobject_2t, L4::Kobject_3t,
39  * or L4::Kobject_x) for inheritance, otherwise these classes cannot be used
40  * as RPC interfaces.
41  *
42  * \attention Objects derived from Kobject *must* never add any data to
43  * those objects. Kobjects can act only as proxy object
44  * for encapsulating object invocations.
45  */
46 class L4_EXPORT Kobject
47 {
48 private:
49  Kobject();
50  Kobject(Kobject const &);
51  Kobject &operator = (Kobject const &);
52 
53  template<typename T> friend struct Kobject_typeid;
54 
55 protected:
56  typedef Typeid::Iface<L4_PROTO_META, Kobject> __Iface;
57  typedef Typeid::Iface_list<__Iface> __Iface_list;
58 
59  /**
60  * \internal
61  * Get a pointer to the L4Re dynamic type information for this class.
62  *
63  * \note This function is used by L4::kobject_typeid().
64  */
65  struct __Kobject_typeid
66  {
67  typedef Type_info::Demand_t<> Demand;
68  static Type_info const _m;
69  };
70 
71  /**
72  * Return capability selector.
73  *
74  * \return Capability selector.
75  *
76  * This method is for derived classes to gain access to the actual
77  * capability selector.
78  */
79  l4_cap_idx_t cap() const throw() { return _c(); }
80 
81 private:
82 
83  /**
84  * \internal
85  * Used to convert the `this` pointer to a capability selector.
86  */
87  l4_cap_idx_t _c() const throw()
88  { return reinterpret_cast<l4_cap_idx_t>(this) & L4_CAP_MASK; }
89 
90 public:
91  /**
92  * Decrement the in kernel reference counter for the object.
93  *
94  * \param diff The delta that shall be subtracted from the reference count.
95  * \utcb{utcb}
96  *
97  * This function is intended for servers to be able to remove the servers
98  * own capability from the counted references. This leads to the semantics
99  * that the kernel will delete the object even if the capability of the
100  * server is valid. The server can detect the deletion by polling its
101  * capabilities or by using the IPC-gate deletion IRQs. And to cleanup
102  * if the clients dropped the last reference (capability) to the object.
103  */
104  l4_msgtag_t dec_refcnt(l4_mword_t diff, l4_utcb_t *utcb = l4_utcb())
105  { return l4_kobject_dec_refcnt_u(cap(), diff, utcb); }
106 };
107 
108 template<typename Derived, long PROTO = L4::PROTO_ANY,
109  typename S_DEMAND = Type_info::Demand_t<> >
110 struct Kobject_0t : Kobject_t<Derived, L4::Kobject, PROTO, S_DEMAND> {};
111 
112 }
113