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
27namespace 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 */
46class L4_EXPORT Kobject
47{
48private:
49  Kobject();
50  Kobject(Kobject const  &);
51  Kobject &operator = (Kobject const &);
52
53  template<typename T> friend struct Kobject_typeid;
54
55protected:
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 noexcept { return _c(); }
80
81private:
82
83  /**
84   * \internal
85   * Used to convert the `this` pointer to a capability selector.
86   */
87  l4_cap_idx_t _c() const noexcept
88  { return reinterpret_cast<l4_cap_idx_t>(this) & L4_CAP_MASK; }
89
90public:
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   * \return Syscall return tag
98   *
99   * This function is intended for servers to be able to remove the servers
100   * own capability from the counted references.  This leads to the semantics
101   * that the kernel will delete the object even if the capability of the
102   * server is valid.  The server can detect the deletion by polling its
103   * capabilities or by using the IPC-gate deletion IRQs.  And to cleanup
104   * if the clients dropped the last reference (capability) to the object.
105   *
106   * This function only succeeds on a kernel object of type L4::Ipc_gate which
107   * has the server right (#L4_FPAGE_C_IPCGATE_SVR). For other kernel objects,
108   * -L4_ENOSYS is returned.
109   */
110  l4_msgtag_t dec_refcnt(l4_mword_t diff, l4_utcb_t *utcb = l4_utcb())
111  { return l4_kobject_dec_refcnt_u(cap(), diff, utcb); }
112};
113
114template<typename Derived, long PROTO = L4::PROTO_ANY,
115         typename S_DEMAND = Type_info::Demand_t<> >
116struct Kobject_0t : Kobject_t<Derived, L4::Kobject, PROTO, S_DEMAND> {};
117
118}
119
120