Commit db9d479a authored by David Vernet's avatar David Vernet Committed by Alexei Starovoitov
Browse files

bpf,docs: Update documentation to reflect new task kfuncs 



Now that struct task_struct objects are RCU safe, and bpf_task_acquire()
can return NULL, we should update the BPF task kfunc documentation to
reflect the current state of the API.

Signed-off-by: default avatarDavid Vernet <void@manifault.com>
Link: https://lore.kernel.org/r/20230331195733.699708-4-void@manifault.com


Signed-off-by: default avatarAlexei Starovoitov <ast@kernel.org>
parent f85671c6

Documentation/bpf/kfuncs.rst

+43 −6
Original line number Diff line number Diff line
@@ -471,7 +471,7 @@ struct_ops callback arg. For example: 
		struct task_struct *acquired;



		acquired = bpf_task_acquire(task);



		if (acquired)

			/*

			 * In a typical program you'd do something like store

			 * the task in a map, and the map will automatically
@@ -481,6 +481,43 @@ struct_ops callback arg. For example: 
		return 0;

	}





References acquired on ``struct task_struct *`` objects are RCU protected.

Therefore, when in an RCU read region, you can obtain a pointer to a task

embedded in a map value without having to acquire a reference:



.. code-block:: c



	#define private(name) SEC(".data." #name) __hidden __attribute__((aligned(8)))

	private(TASK) static struct task_struct *global;



	/**

	 * A trivial example showing how to access a task stored

	 * in a map using RCU.

	 */

	SEC("tp_btf/task_newtask")

	int BPF_PROG(task_rcu_read_example, struct task_struct *task, u64 clone_flags)

	{

		struct task_struct *local_copy;



		bpf_rcu_read_lock();

		local_copy = global;

		if (local_copy)

			/*

			 * We could also pass local_copy to kfuncs or helper functions here,

			 * as we're guaranteed that local_copy will be valid until we exit

			 * the RCU read region below.

			 */

			bpf_printk("Global task %s is valid", local_copy->comm);

		else

			bpf_printk("No global task found");

		bpf_rcu_read_unlock();



		/* At this point we can no longer reference local_copy. */



		return 0;

	}



----



A BPF program can also look up a task from a pid. This can be useful if the