1 // Copyright 2021 The Pigweed Authors
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License"); you may not
4 // use this file except in compliance with the License. You may obtain a copy of
5 // the License at
6 //
7 // https://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12 // License for the specific language governing permissions and limitations under
13 // the License.
14 #pragma once
15
16 #include "FreeRTOS.h"
17 #include "pw_protobuf/encoder.h"
18 #include "pw_span/span.h"
19 #include "pw_status/status.h"
20 #include "pw_thread/snapshot.h"
21 #include "pw_thread_protos/thread.pwpb.h"
22 #include "task.h"
23
24 namespace pw::thread::freertos {
25
26 // Captures all FreeRTOS threads in a system as part of a snapshot.
27 //
28 // Note: this requires the pw_thread_freertos:freertos_tskcb backend to be
29 // set in order to access the stack limits inside of tskTCB.
30 //
31 // An updated running_thread_stack_pointer can be provided in order for the
32 // running thread's context to reflect the running state. Some platforms store
33 // the last running stack pointer back into TCB to be retrieved. For ARM, you
34 // might do something like this:
35 //
36 // // Capture PSP.
37 // void* stack_ptr = 0;
38 // asm volatile("mrs %0, psp\n" : "=r"(stack_ptr));
39 // pw::thread::ProcessThreadStackCallback cb =
40 // [](pw::thread::proto::pwbp::Thread::StreamEncoder& encoder,
41 // pw::ConstByteSpan stack) -> pw::Status {
42 // return encoder.WriteRawStack(stack);
43 // };
44 // pw::thread::freertos::SnapshotThreads(stack_ptr, snapshot_encoder, cb);
45 //
46 // Warning: This is only safe to use when the scheduler and interrupts are
47 // disabled.
48 Status SnapshotThreads(void* running_thread_stack_pointer,
49 proto::pwpb::SnapshotThreadInfo::StreamEncoder& encoder,
50 ProcessThreadStackCallback& thread_stack_callback);
51
52 // If you are unable to capture a more recent stack pointer when snapshotting
53 // threads (or if your port does not require it), fall back to this overload of
54 // SnapshotThreads().
55 //
56 // WARNING: Using this version of SnapshotThreads() may not properly capture
57 // some of the running thread's context. Only use if you know what you're doing.
SnapshotThreads(proto::pwpb::SnapshotThreadInfo::StreamEncoder & encoder,ProcessThreadStackCallback & thread_stack_callback)58 inline Status SnapshotThreads(
59 proto::pwpb::SnapshotThreadInfo::StreamEncoder& encoder,
60 ProcessThreadStackCallback& thread_stack_callback) {
61 return SnapshotThreads(nullptr, encoder, thread_stack_callback);
62 }
63
64 // Captures only the provided thread handle as a pw::thread::Thread proto
65 // message.
66 //
67 // An updated running_thread_stack_pointer must be provided in order for the
68 // running thread's context to reflect the current state. If the thread being
69 // captured is not the running thread, the value is ignored. Note that the
70 // stack pointer in the thread handle is almost always stale on the running
71 // thread.
72 //
73 // Note: this requires the pw_thread_freertos:freertos_tskcb backend to be
74 // set in order to access the stack limits inside of tskTCB.
75 //
76 // Captures the following proto fields:
77 //
78 // pw.thread.Thread:
79 // name
80 // state
81 // stack_start_pointer
82 // stack_end_pointer (if (portSTACK_GROWTH > 0) ||
83 // (configRECORD_STACK_HIGH_ADDRESS == 1))
84 // stack_pointer
85 //
86 Status SnapshotThread(TaskHandle_t thread,
87 eTaskState thread_state,
88 void* running_thread_stack_pointer,
89 proto::pwpb::Thread::StreamEncoder& encoder,
90 ProcessThreadStackCallback& thread_stack_callback);
91
92 } // namespace pw::thread::freertos
93