/*
 * This file and its contents are supplied under the terms of the
 * Common Development and Distribution License ("CDDL"), version 1.0.
 * You may only use this file in accordance with the terms of version
 * 1.0 of the CDDL.
 *
 * A full copy of the text of the CDDL should have accompanied this
 * source.  A copy of the CDDL is also available via the Internet at
 * http://www.illumos.org/license/CDDL.
 */

/*
 * Copyright 2024 Oxide Computer Company
 */

#ifndef _HEXDUMP_H_
#define	_HEXDUMP_H_

/*
 * Header file for the generic hexdump implementation in
 * common/hexdump/hexdump.c
 */

#include <sys/types.h>

#ifndef _KERNEL
#include <stdio.h>
#endif

#ifdef __cplusplus
extern "C" {
#endif

typedef enum {
	/*
	 * Include a header row showing byte positions.
	 */
	HDF_HEADER		= 1 << 0,
	/*
	 * Include the address of the first byte for each row at the left.
	 */
	HDF_ADDRESS		= 1 << 1,
	/*
	 * Include an ASCII table at the right hand side with unprintable bytes
	 * displayed as '.'.
	 */
	HDF_ASCII		= 1 << 2,
	/*
	 * If the data is not naturally aligned to the paragraph size, start
	 * the table from an aligned address and indicate where the data starts
	 * with a marker in the table header (if enabled). Missing data are
	 * shown with space characters.
	 */
	HDF_ALIGN		= 1 << 3,
	/*
	 * Suppress duplicate lines in the output, replacing them with a single
	 * "*".
	 */
	HDF_DEDUP		= 1 << 4,
	/*
	 * When laying out byte columns, use two spaces instead of one. This
	 * results in the data being more spread out and easier to read in some
	 * circumstances.
	 */
	HDF_DOUBLESPACE		= 1 << 5,
} hexdump_flag_t;

/*
 * Most consumers of the hexdump routines should use this default set of flags
 * so we have consistent output across the gate.
 */
#define	HDF_DEFAULT	(HDF_HEADER | HDF_ADDRESS | HDF_ASCII)

/*
 * Consumers of this code should treat this as an opaque type and initialise it
 * with a call to hexdump_init(). It is defined here so that it can be placed
 * on the stack which is particularly useful during early boot, before the kmem
 * system is ready.
 */
typedef struct {
	uint64_t	h_addr;		/* display address */
	uint8_t		h_addrwidth;	/* Minimum address width */
	uint8_t		h_width;	/* bytes per row */
	uint8_t		h_grouping;	/* display bytes in groups of.. */
	uint8_t		h_indent;	/* Left indent */
	uint8_t		h_marker;	/* marker offset */
	uint8_t		*h_buf;		/* optional pre-allocated buffer... */
	size_t		h_buflen;	/* ...and its size */
} hexdump_t;

/*
 * Initialise and finalise a hexdump_t.
 */
extern void hexdump_init(hexdump_t *);
extern void hexdump_fini(hexdump_t *);

/*
 * Set the start address that corresponds to the provided data. This is used to
 * display addresses in conjunction with the HDF_ADDRESS option.
 */
extern void hexdump_set_addr(hexdump_t *, uint64_t);

/*
 * Set a minimum width, in characters, for the addresses shown in conjunction
 * with the HDF_ADDRESS option. The default behaviour is to calculate the width
 * required to show all addresses and use that for all rows.
 */
extern void hexdump_set_addrwidth(hexdump_t *, uint8_t);

/*
 * Select the number of bytes per line. The default is 16.
 */
extern void hexdump_set_width(hexdump_t *, uint8_t);

/*
 * Group bytes together. The default grouping is 1 which results in each byte
 * being displayed surrounded by space. As a readability improvement an extra
 * space is added after every 8 bytes when using a grouping of 1.
 */
extern void hexdump_set_grouping(hexdump_t *, uint8_t);

/*
 * Set a number of spaces that should precede each row as an indent.
 */
extern void hexdump_set_indent(hexdump_t *, uint8_t);

/*
 * Set a marker in the header for the start of interesting data. This will only
 * be displayed if the header is enabled with the HDF_HEADER option, and if the
 * marker value is less than the configured row width.
 */
extern void hexdump_set_marker(hexdump_t *, uint8_t);

/*
 * Provide a scratch space working buffer. This is necessary in early boot,
 * before kmem is ready.
 */
extern void hexdump_set_buf(hexdump_t *, uint8_t *, size_t);

/*
 * The hexdump() function that does the work. It takes the following arguments:
 *
 *	const uint8_t *addr	- a pointer to the data to be dumped
 *	size_t len		- the length of the data
 *	hexdump_flag_t flags	- flags as per the definitions above
 *	hexdump_cb_f callback	- fucntion called for each table row
 *	void *callback_arg	- pointer passed to callback function
 *
 * More customisation can be achieved by using hexdumph() which takes an
 * additional hexdump_t *.
 */
typedef int (*hexdump_cb_f)(void *, uint64_t, const char *, size_t);
extern int hexdump(const uint8_t *, size_t, hexdump_flag_t,
    hexdump_cb_f, void *);

/*
 * A version that takes a hexdump_t allowing for more customisation.
 */
extern int hexdumph(hexdump_t *, const uint8_t *, size_t, hexdump_flag_t,
    hexdump_cb_f, void *);

#ifndef _KERNEL
/*
 * Convenience wrappers in non-kernel context that output each table row to
 * the provided FILE *.
 */
extern int hexdump_file(const uint8_t *, size_t, hexdump_flag_t, FILE *);
extern int hexdump_fileh(hexdump_t *, const uint8_t *, size_t, hexdump_flag_t,
    FILE *);
#endif /* _KERNEL */

#ifdef __cplusplus
}
#endif

#endif /* _HEXDUMP_H_ */