)]}' { "commit": "7a8e76a3829f1067b70f715771ff88baf2fbf3c3", "tree": "71126d4ad6f89abd00cac688318aff14323a96bb", "parents": [ "5aa60c6073456812251caf9177cb921b2de68f77" ], "author": { "name": "Steven Rostedt", "email": "rostedt@goodmis.org", "time": "Mon Sep 29 23:02:38 2008 -0400" }, "committer": { "name": "Ingo Molnar", "email": "mingo@elte.hu", "time": "Tue Oct 14 10:38:54 2008 +0200" }, "message": "tracing: unified trace buffer\n\nThis is a unified tracing buffer that implements a ring buffer that\nhopefully everyone will eventually be able to use.\n\nThe events recorded into the buffer have the following structure:\n\n struct ring_buffer_event {\n\tu32 type:2, len:3, time_delta:27;\n\tu32 array[];\n };\n\nThe minimum size of an event is 8 bytes. All events are 4 byte\naligned inside the buffer.\n\nThere are 4 types (all internal use for the ring buffer, only\nthe data type is exported to the interface users).\n\n RINGBUF_TYPE_PADDING: this type is used to note extra space at the end\n\tof a buffer page.\n\n RINGBUF_TYPE_TIME_EXTENT: This type is used when the time between events\n\tis greater than the 27 bit delta can hold. We add another\n\t32 bits, and record that in its own event (8 byte size).\n\n RINGBUF_TYPE_TIME_STAMP: (Not implemented yet). This will hold data to\n\thelp keep the buffer timestamps in sync.\n\nRINGBUF_TYPE_DATA: The event actually holds user data.\n\nThe \"len\" field is only three bits. Since the data must be\n4 byte aligned, this field is shifted left by 2, giving a\nmax length of 28 bytes. If the data load is greater than 28\nbytes, the first array field holds the full length of the\ndata load and the len field is set to zero.\n\nExample, data size of 7 bytes:\n\n\ttype \u003d RINGBUF_TYPE_DATA\n\tlen \u003d 2\n\ttime_delta: \u003ctime-stamp\u003e - \u003cprev_event-time-stamp\u003e\n\tarray[0..1]: \u003c7 bytes of data\u003e \u003c1 byte empty\u003e\n\nThis event is saved in 12 bytes of the buffer.\n\nAn event with 82 bytes of data:\n\n\ttype \u003d RINGBUF_TYPE_DATA\n\tlen \u003d 0\n\ttime_delta: \u003ctime-stamp\u003e - \u003cprev_event-time-stamp\u003e\n\tarray[0]: 84 (Note the alignment)\n\tarray[1..14]: \u003c82 bytes of data\u003e \u003c2 bytes empty\u003e\n\nThe above event is saved in 92 bytes (if my math is correct).\n82 bytes of data, 2 bytes empty, 4 byte header, 4 byte length.\n\nDo not reference the above event struct directly. Use the following\nfunctions to gain access to the event table, since the\nring_buffer_event structure may change in the future.\n\nring_buffer_event_length(event): get the length of the event.\n\tThis is the size of the memory used to record this\n\tevent, and not the size of the data pay load.\n\nring_buffer_time_delta(event): get the time delta of the event\n\tThis returns the delta time stamp since the last event.\n\tNote: Even though this is in the header, there should\n\t\tbe no reason to access this directly, accept\n\t\tfor debugging.\n\nring_buffer_event_data(event): get the data from the event\n\tThis is the function to use to get the actual data\n\tfrom the event. Note, it is only a pointer to the\n\tdata inside the buffer. This data must be copied to\n\tanother location otherwise you risk it being written\n\tover in the buffer.\n\nring_buffer_lock: A way to lock the entire buffer.\nring_buffer_unlock: unlock the buffer.\n\nring_buffer_alloc: create a new ring buffer. Can choose between\n\toverwrite or consumer/producer mode. Overwrite will\n\toverwrite old data, where as consumer producer will\n\tthrow away new data if the consumer catches up with the\n\tproducer. The consumer/producer is the default.\n\nring_buffer_free: free the ring buffer.\n\nring_buffer_resize: resize the buffer. Changes the size of each cpu\n\tbuffer. Note, it is up to the caller to provide that\n\tthe buffer is not being used while this is happening.\n\tThis requirement may go away but do not count on it.\n\nring_buffer_lock_reserve: locks the ring buffer and allocates an\n\tentry on the buffer to write to.\nring_buffer_unlock_commit: unlocks the ring buffer and commits it to\n\tthe buffer.\n\nring_buffer_write: writes some data into the ring buffer.\n\nring_buffer_peek: Look at a next item in the cpu buffer.\nring_buffer_consume: get the next item in the cpu buffer and\n\tconsume it. That is, this function increments the head\n\tpointer.\n\nring_buffer_read_start: Start an iterator of a cpu buffer.\n\tFor now, this disables the cpu buffer, until you issue\n\ta finish. This is just because we do not want the iterator\n\tto be overwritten. This restriction may change in the future.\n\tBut note, this is used for static reading of a buffer which\n\tis usually done \"after\" a trace. Live readings would want\n\tto use the ring_buffer_consume above, which will not\n\tdisable the ring buffer.\n\nring_buffer_read_finish: Finishes the read iterator and reenables\n\tthe ring buffer.\n\nring_buffer_iter_peek: Look at the next item in the cpu iterator.\nring_buffer_read: Read the iterator and increment it.\nring_buffer_iter_reset: Reset the iterator to point to the beginning\n\tof the cpu buffer.\nring_buffer_iter_empty: Returns true if the iterator is at the end\n\tof the cpu buffer.\n\nring_buffer_size: returns the size in bytes of each cpu buffer.\n\tNote, the real size is this times the number of CPUs.\n\nring_buffer_reset_cpu: Sets the cpu buffer to empty\nring_buffer_reset: sets all cpu buffers to empty\n\nring_buffer_swap_cpu: swaps a cpu buffer from one buffer with a\n\tcpu buffer of another buffer. This is handy when you\n\twant to take a snap shot of a running trace on just one\n\tcpu. Having a backup buffer, to swap with facilitates this.\n\tFtrace max latencies use this.\n\nring_buffer_empty: Returns true if the ring buffer is empty.\nring_buffer_empty_cpu: Returns true if the cpu buffer is empty.\n\nring_buffer_record_disable: disable all cpu buffers (read only)\nring_buffer_record_disable_cpu: disable a single cpu buffer (read only)\nring_buffer_record_enable: enable all cpu buffers.\nring_buffer_record_enabl_cpu: enable a single cpu buffer.\n\nring_buffer_entries: The number of entries in a ring buffer.\nring_buffer_overruns: The number of entries removed due to writing wrap.\n\nring_buffer_time_stamp: Get the time stamp used by the ring buffer\nring_buffer_normalize_time_stamp: normalize the ring buffer time stamp\n\tinto nanosecs.\n\nI still need to implement the GTOD feature. But we need support from\nthe cpu frequency infrastructure. But this can be done at a later\ntime without affecting the ring buffer interface.\n\nSigned-off-by: Steven Rostedt \u003csrostedt@redhat.com\u003e\nSigned-off-by: Ingo Molnar \u003cmingo@elte.hu\u003e\n", "tree_diff": [ { "type": "add", "old_id": "0000000000000000000000000000000000000000", "old_mode": 0, "old_path": "/dev/null", "new_id": "c52375b8330dbe16003339e690498d75bbcb197c", "new_mode": 33188, "new_path": "include/linux/ring_buffer.h" }, { "type": "modify", "old_id": "4feb3c81f94dfae45a22fca464e17ca5742e059f", "old_mode": 33188, "old_path": "kernel/trace/Kconfig", "new_id": "396aea11398eaf20ffc8c9ce3b67b9fb9a1ce4ec", "new_mode": 33188, "new_path": "kernel/trace/Kconfig" }, { "type": "modify", "old_id": "35a07f7cfa865ab9dfe7853ad6603f824e850651", "old_mode": 33188, "old_path": "kernel/trace/Makefile", "new_id": "a85dfba88ba0402d5614d015c5faed60fe4abc55", "new_mode": 33188, "new_path": "kernel/trace/Makefile" }, { "type": "add", "old_id": "0000000000000000000000000000000000000000", "old_mode": 0, "old_path": "/dev/null", "new_id": "830a2930dd9196cc9cf0d8b651cfbf2db9ff4349", "new_mode": 33188, "new_path": "kernel/trace/ring_buffer.c" } ] }