xref: /aosp_15_r20/system/extras/ioshark/README (revision 288bf5226967eb3dac5cce6c939ccc2a7f2b4fe5)

IOshark is a repeatable application workload storage benchmark. You
can find more documentation on IOshark at :
https://docs.google.com/a/google.com/document/d/1Bhq7iNPVc_JzwRrkmZqcPjMvWgpHX0r3Ncq-ZsRNOBA/edit?usp=sharing

The short summary of what IOshark is : IOshark has 2 components, one
is a strace+ftrace compiler that takes straces and select ftraces fed
into it and compiles this into bytecodes (stored in *.wl files). The
compiler runs on a Linux host. The second component (which runs on the
device) is the tester that takes as input the bytecode files (*.wl
files) and executes them on the device.

How to Run :
----------
- First collect straces and compile these into bytecodes. The wrapper
script provided (collect-straces.sh) collects straces, ships them to
the host where the script runs, compiles and packages up the bytecode
files into a wl.tar file.
- Ship the wl.tar file and the iostark_bench binaries to the target
device (on /data/local/tmp say). Explode the tarfile.
- Run the tester. "ioshark_bench *.wl" runs the test with default
options. Supported ioshark_bench options :
-b : Explicitly specify a blockdev (to get IO stats from from
/proc/diskstats).
-d : Preserve the delays between successive filesystem syscalls as
seen in the original straces.
-n <N> : Run for N iterations
-t <N> : Limit to N threads. By default (without this option), IOshark
will launch as many threads as there are input files, so 1 thread/file.
-v : verbose. Chatty mode.
-s : One line summary.
-q : Don't create the files in read-only partitions like /system and
/vendor. Instead do reads on those files.

FILE FORMAT :
-----------

Each IOshark workload file is composed of the following

Header
File State : Table of File Entries. Each entry describes a file
File Op : Table of File Operations. One entry describes one operation

Each of the above is described below :

Note : Everything is in Big Endian byte order.

Header {
       /* IOshark version number */
       u_int64_t	ioshark_version;
       /* Total number of files used in this IOshark workload file */
       u_int64_t	num_files;
       /* Total number of IO operations in this IOshark workload file */
       u_int64_t       num_io_operations;
}

File State {
       u_int64_t	fileno;
       u_int64_t	size;
       u_int64_t 	global_filename_ix;
}

File Op {
	/* delta us between previous file op and this */
	u_int64_t		delta_us;
#define file_op			file_op_union.file_op_u
	union {
		enum file_op		file_op_u;
		int32_t			enum_size;
	} file_op_union;
	u_int64_t		fileno;
	union {
		struct lseek_args {
#define lseek_offset	u.lseek_a.offset
#define lseek_action	u.lseek_a.action
			u_int64_t	offset;
			int32_t		action;
		} lseek_a;
		struct prw_args {
#define prw_offset	u.prw_a.offset
#define prw_len		u.prw_a.len
			u_int64_t	offset;
			u_int64_t	len;
		} prw_a;
#define rw_len		u.rw_a.len
		struct rw_args {
			u_int64_t	len;
		} rw_a;
#define mmap_offset	u.mmap_a.offset
#define mmap_len	u.mmap_a.len
#define mmap_prot	u.mmap_a.prot
		struct mmap_args {
			u_int64_t	offset;
			u_int64_t	len;
			int32_t		prot;
	} mmap_a;
#define open_flags	u.open_a.flags
#define open_mode	u.open_a.mode
		struct open_args {
			int32_t		flags;
			int32_t		mode;
		} open_a;
	} u;

}