1 // Copyright 2016 The Fuchsia Authors
2 //
3 // Use of this source code is governed by a MIT-style
4 // license that can be found in the LICENSE file or at
5 // https://opensource.org/licenses/MIT
6 
7 #pragma once
8 
9 #include <stdint.h>
10 
11 #include <kernel/event.h>
12 #include <object/dispatcher.h>
13 #include <object/message_packet.h>
14 
15 #include <zircon/rights.h>
16 #include <zircon/types.h>
17 
18 #include <fbl/canary.h>
19 #include <fbl/intrusive_double_list.h>
20 #include <fbl/mutex.h>
21 #include <fbl/ref_counted.h>
22 #include <ktl/unique_ptr.h>
23 
24 class ChannelDispatcher final :
25     public PeeredDispatcher<ChannelDispatcher, ZX_DEFAULT_CHANNEL_RIGHTS> {
26 public:
27     class MessageWaiter;
28 
29     static zx_status_t Create(fbl::RefPtr<Dispatcher>* dispatcher0,
30                               fbl::RefPtr<Dispatcher>* dispatcher1, zx_rights_t* rights);
31 
32     ~ChannelDispatcher() final;
get_type()33     zx_obj_type_t get_type() const final { return ZX_OBJ_TYPE_CHANNEL; }
34     zx_status_t add_observer(StateObserver* observer) final;
35 
36     // Read from this endpoint's message queue.
37     // |msg_size| and |msg_handle_count| are in-out parameters. As input, they specify the maximum
38     // size and handle count, respectively. On ZX_OK or ZX_ERR_BUFFER_TOO_SMALL, they specify the
39     // actual size and handle count of the next message. The next message is returned in |*msg| on
40     // ZX_OK and also on ZX_ERR_BUFFER_TOO_SMALL when |may_discard| is set.
41     zx_status_t Read(zx_koid_t owner,
42                      uint32_t* msg_size,
43                      uint32_t* msg_handle_count,
44                      MessagePacketPtr* msg,
45                      bool may_disard);
46 
47     // Write to the opposing endpoint's message queue. |owner| is the process attempting to
48     // write to the channel, or ZX_KOID_INVALID if kernel is doing it. If |owner| does not
49     // match what was last set by Dispatcher::set_owner() the call will fail.
50     zx_status_t Write(zx_koid_t owner,
51                       MessagePacketPtr msg) TA_NO_THREAD_SAFETY_ANALYSIS;
52 
53     // Perform a transacted Write + Read. |owner| is the process attempting to write
54     // to the channel, or ZX_KOID_INVALID if kernel is doing it. If |owner| does not
55     // match what was last set by Dispatcher::set_owner() the call will fail.
56     zx_status_t Call(zx_koid_t owner,
57                      MessagePacketPtr msg,
58                      zx_time_t deadline,
59                      MessagePacketPtr* reply) TA_NO_THREAD_SAFETY_ANALYSIS;
60 
61     // Performs the wait-then-read half of Call.  This is meant for retrying
62     // after an interruption caused by suspending.
63     zx_status_t ResumeInterruptedCall(MessageWaiter* waiter, zx_time_t deadline, TimerSlack slack,
64                                       MessagePacketPtr* reply);
65 
66     // MessageWaiter's state is guarded by the lock of the
67     // owning ChannelDispatcher, and Deliver(), Signal(), Cancel(),
68     // and EndWait() methods must only be called under
69     // that lock.
70     //
71     // MessageWaiters are embedded in ThreadDispatchers, and the channel_ pointer
72     // can only be manipulated by their thread (via BeginWait() or EndWait()), and
73     // only transitions to nullptr while holding the ChannelDispatcher's lock.
74     //
75     // See also: comments in ChannelDispatcher::Call()
76     class MessageWaiter : public fbl::DoublyLinkedListable<MessageWaiter*> {
77     public:
MessageWaiter()78         MessageWaiter() : txid_(0), status_(ZX_ERR_BAD_STATE) {
79         }
80 
81         ~MessageWaiter();
82 
83         zx_status_t BeginWait(fbl::RefPtr<ChannelDispatcher> channel);
84         void Deliver(MessagePacketPtr msg);
85         void Cancel(zx_status_t status);
get_channel()86         fbl::RefPtr<ChannelDispatcher> get_channel() { return channel_; }
get_txid()87         zx_txid_t get_txid() const { return txid_; }
set_txid(zx_txid_t txid)88         void set_txid(zx_txid_t txid) { txid_ = txid; };
89         zx_status_t Wait(zx_time_t deadline, TimerSlack slack);
90         // Returns any delivered message via out and the status.
91         zx_status_t EndWait(MessagePacketPtr* out);
92 
93     private:
94         fbl::RefPtr<ChannelDispatcher> channel_;
95         MessagePacketPtr msg_;
96         // TODO(teisenbe/swetland): Investigate hoisting this outside to reduce
97         // userthread size
98         Event event_;
99         zx_txid_t txid_;
100         zx_status_t status_;
101     };
102 
103     // PeeredDispatcher implementation.
104     void on_zero_handles_locked() TA_REQ(get_lock());
105     void OnPeerZeroHandlesLocked() TA_REQ(get_lock());
106 
107     void set_owner(zx_koid_t new_owner) final;
108 
109 private:
110     using MessageList = fbl::DoublyLinkedList<MessagePacketPtr>;
111     using WaiterList = fbl::DoublyLinkedList<MessageWaiter*>;
112 
113     void RemoveWaiter(MessageWaiter* waiter);
114 
115     explicit ChannelDispatcher(fbl::RefPtr<PeerHolder<ChannelDispatcher>> holder);
116     void Init(fbl::RefPtr<ChannelDispatcher> other);
117     void WriteSelf(MessagePacketPtr msg) TA_REQ(get_lock());
118     zx_status_t UserSignalSelf(uint32_t clear_mask, uint32_t set_mask) TA_REQ(get_lock());
119 
120     fbl::Canary<fbl::magic("CHAN")> canary_;
121 
122     MessageList messages_ TA_GUARDED(get_lock());
123     uint64_t message_count_ TA_GUARDED(get_lock()) = 0;
124     uint64_t max_message_count_ TA_GUARDED(get_lock()) = 0;
125     // Tracks the process that is allowed to issue calls, for example write
126     // to the opposite end. Without it, one can see writes out of order with
127     // respect of the previous and current owner. We avoid locking and updating
128     // the |owner_| if the new owner is kernel, which happens when the endpoint
129     // is written into a channel or during process destruction.
130     zx_koid_t owner_ TA_GUARDED(get_lock()) = ZX_KOID_INVALID;
131 
132     uint32_t txid_ TA_GUARDED(get_lock()) = 0;
133     WaiterList waiters_ TA_GUARDED(get_lock());
134 };
135