tracing_map_create(9)

💖 tracing_map_create(9) 💖

okay bestie, welcome to tracing_map_create(9) from the Kernel API Manual — this is the kernel API page for a lock-free map and element pool, and it's giving main character energy, lowkey iconic 💅✨

🌸 NAME 🌸

tracing_map_create — Create a lock-free map and element pool

✨ SYNOPSIS ✨

struct tracing_map * tracing_map_create (unsigned int map_bits ,
       unsigned int key_size , const struct tracing_map_ops *ops , void
       *private_data );

🎀 ARGUMENTS 🎀

• map_bits — The size of the map (2 ** map_bits)
• key_size — The size of the key for the map in bytes
• ops — Optional client-defined tracing_map_ops instance
• private_data — Client data associated with the map

🦋 DESCRIPTION 🦋

Okay so tracing_map_create creates and sets up a map to contain 2 ** map_bits number of elements (internally maintained as 'max_elts' in struct tracing_map). Before using, map fields should be added to the map with tracing_map_add_sum_field and tracing_map_add_key_field. tracing_map_init should then be called to allocate the array of tracing_map_elts, in order to avoid allocating anything in the map insertion path. The user-specified map size reflects the maximum number of elements that can be contained in the table requested by the user — internally we double that in order to keep the table sparse and keep collisions manageable.

A tracing_map is a special-purpose map designed to aggregate or tracing_map_elt, which is attached by the map to a given key.

Vibe check: tracing_map_create sets up the map itself, and provides operations for inserting tracing_map_elts, but it doesn't allocate the tracing_map_elts themselves, or provide a means for describing the keys or sums associated with the tracing_map_elts. All tracing_map_elts for a given map have the same set of sums and keys, which are defined by the client using the functions tracing_map_add_key_field and tracing_map_add_sum_field. Once the fields are defined, the pool of elements allocated for the map can be created, which occurs when the client code calls tracing_map_init.

When tracing_map_init returns, tracing_map_elt elements can be inserted into the map using tracing_map_insert. When called, tracing_map_insert grabs a free tracing_map_elt from the pool, or finds an existing match in the map and in either case returns it. The client can then use tracing_map_update_sum and tracing_map_read_sum to update or read a given sum field for the tracing_map_elt.

The client can at any point retrieve and traverse the current set of inserted tracing_map_elts in a tracing_map, via tracing_map_sort_entries. Sorting can be done on any field, including keys.

See tracing_map.h for a description of tracing_map_ops.

🔥 RETURN 🔥

It returns the tracing_map pointer if successful, and ERR_PTR if not.

👑 SEE ALSO 👑

Kernel file ./kernel/trace/tracing_map.c — plus tracing_map_update_sum(9), tracing_map_read_sum(9), tracing_map_set_var(9), tracing_map_var_set(9), tracing_map_read_var(9), tracing_map_read_var_once(9), tracing_map_add_sum_field(9), tracing_map_add_var(9), tracing_map_add_key_field(9), tracing_map_insert(9), tracing_map_lookup(9), tracing_map_destroy(9), tracing_map_clear(9), tracing_map_init(9), tracing_map_destroy_sort_entries(9), tracing_map_sort_entries(9)

---

okay that's the whole page, bestie 🫶 made with love from source/version ./kernel/trace, dated October 2026, and you're reading tracing_map_create(9) — periodt 💅✨