1/* SPDX-License-Identifier: GPL-2.0 */ 2#ifndef _LINUX_SEQ_BUF_H 3#define _LINUX_SEQ_BUF_H 4 5#include <linux/bug.h> 6#include <linux/minmax.h> 7#include <linux/seq_file.h> 8#include <linux/types.h> 9 10/* 11 * Trace sequences are used to allow a function to call several other functions 12 * to create a string of data to use. 13 */ 14 15/** 16 * struct seq_buf - seq buffer structure 17 * @buffer: pointer to the buffer 18 * @size: size of the buffer 19 * @len: the amount of data inside the buffer 20 */ 21struct seq_buf { 22 char *buffer; 23 size_t size; 24 size_t len; 25}; 26 27#define DECLARE_SEQ_BUF(NAME, SIZE) \ 28 struct seq_buf NAME = { \ 29 .buffer = (char[SIZE]) { 0 }, \ 30 .size = SIZE, \ 31 } 32 33static inline void seq_buf_clear(struct seq_buf *s) 34{ 35 s->len = 0; 36 if (s->size) 37 s->buffer[0] = '\0'; 38} 39 40static inline void 41seq_buf_init(struct seq_buf *s, char *buf, unsigned int size) 42{ 43 s->buffer = buf; 44 s->size = size; 45 seq_buf_clear(s); 46} 47 48/* 49 * seq_buf have a buffer that might overflow. When this happens 50 * len is set to be greater than size. 51 */ 52static inline bool 53seq_buf_has_overflowed(struct seq_buf *s) 54{ 55 return s->len > s->size; 56} 57 58static inline void 59seq_buf_set_overflow(struct seq_buf *s) 60{ 61 s->len = s->size + 1; 62} 63 64/* 65 * How much buffer is left on the seq_buf? 66 */ 67static inline unsigned int 68seq_buf_buffer_left(struct seq_buf *s) 69{ 70 if (seq_buf_has_overflowed(s)) 71 return 0; 72 73 return s->size - s->len; 74} 75 76/* How much buffer was written? */ 77static inline unsigned int seq_buf_used(struct seq_buf *s) 78{ 79 return min(s->len, s->size); 80} 81 82/** 83 * seq_buf_str - get NUL-terminated C string from seq_buf 84 * @s: the seq_buf handle 85 * 86 * This makes sure that the buffer in @s is NUL-terminated and 87 * safe to read as a string. 88 * 89 * Note, if this is called when the buffer has overflowed, then 90 * the last byte of the buffer is zeroed, and the len will still 91 * point passed it. 92 * 93 * After this function is called, s->buffer is safe to use 94 * in string operations. 95 * 96 * Returns: @s->buf after making sure it is terminated. 97 */ 98static inline const char *seq_buf_str(struct seq_buf *s) 99{ 100 if (WARN_ON(s->size == 0)) 101 return ""; 102 103 if (seq_buf_buffer_left(s)) 104 s->buffer[s->len] = 0; 105 else 106 s->buffer[s->size - 1] = 0; 107 108 return s->buffer; 109} 110 111/** 112 * seq_buf_get_buf - get buffer to write arbitrary data to 113 * @s: the seq_buf handle 114 * @bufp: the beginning of the buffer is stored here 115 * 116 * Returns: the number of bytes available in the buffer, or zero if 117 * there's no space. 118 */ 119static inline size_t seq_buf_get_buf(struct seq_buf *s, char **bufp) 120{ 121 WARN_ON(s->len > s->size + 1); 122 123 if (s->len < s->size) { 124 *bufp = s->buffer + s->len; 125 return s->size - s->len; 126 } 127 128 *bufp = NULL; 129 return 0; 130} 131 132/** 133 * seq_buf_commit - commit data to the buffer 134 * @s: the seq_buf handle 135 * @num: the number of bytes to commit 136 * 137 * Commit @num bytes of data written to a buffer previously acquired 138 * by seq_buf_get_buf(). To signal an error condition, or that the data 139 * didn't fit in the available space, pass a negative @num value. 140 */ 141static inline void seq_buf_commit(struct seq_buf *s, int num) 142{ 143 if (num < 0) { 144 seq_buf_set_overflow(s); 145 } else { 146 /* num must be negative on overflow */ 147 BUG_ON(s->len + num > s->size); 148 s->len += num; 149 } 150} 151 152extern __printf(2, 3) 153int seq_buf_printf(struct seq_buf *s, const char *fmt, ...); 154extern __printf(2, 0) 155int seq_buf_vprintf(struct seq_buf *s, const char *fmt, va_list args); 156extern int seq_buf_print_seq(struct seq_file *m, struct seq_buf *s); 157extern int seq_buf_to_user(struct seq_buf *s, char __user *ubuf, 158 size_t start, int cnt); 159extern int seq_buf_puts(struct seq_buf *s, const char *str); 160extern int seq_buf_putc(struct seq_buf *s, unsigned char c); 161extern int seq_buf_putmem(struct seq_buf *s, const void *mem, unsigned int len); 162extern int seq_buf_putmem_hex(struct seq_buf *s, const void *mem, 163 unsigned int len); 164extern int seq_buf_path(struct seq_buf *s, const struct path *path, const char *esc); 165extern int seq_buf_hex_dump(struct seq_buf *s, const char *prefix_str, 166 int prefix_type, int rowsize, int groupsize, 167 const void *buf, size_t len, bool ascii); 168 169#ifdef CONFIG_BINARY_PRINTF 170extern int 171seq_buf_bprintf(struct seq_buf *s, const char *fmt, const u32 *binary); 172#endif 173 174void seq_buf_do_printk(struct seq_buf *s, const char *lvl); 175 176#endif /* _LINUX_SEQ_BUF_H */ 177