1/* SPDX-License-Identifier: GPL-2.0+ */
2/*
3 * Generic bounce buffer implementation
4 *
5 * Copyright (C) 2012 Marek Vasut <marex@denx.de>
6 */
7
8#ifndef __INCLUDE_BOUNCEBUF_H__
9#define __INCLUDE_BOUNCEBUF_H__
10
11#include <linux/types.h>
12
13/*
14 * GEN_BB_READ -- Data are read from the buffer eg. by DMA hardware.
15 * The source buffer is copied into the bounce buffer (if unaligned, otherwise
16 * the source buffer is used directly) upon start() call, then the operation
17 * requiring the aligned transfer happens, then the bounce buffer is lost upon
18 * stop() call.
19 */
20#define GEN_BB_READ	(1 << 0)
21/*
22 * GEN_BB_WRITE -- Data are written into the buffer eg. by DMA hardware.
23 * The source buffer starts in an undefined state upon start() call, then the
24 * operation requiring the aligned transfer happens, then the bounce buffer is
25 * copied into the destination buffer (if unaligned, otherwise destination
26 * buffer is used directly) upon stop() call.
27 */
28#define GEN_BB_WRITE	(1 << 1)
29/*
30 * GEN_BB_RW -- Data are read and written into the buffer eg. by DMA hardware.
31 * The source buffer is copied into the bounce buffer (if unaligned, otherwise
32 * the source buffer is used directly) upon start() call, then the  operation
33 * requiring the aligned transfer happens, then the bounce buffer is  copied
34 * into the destination buffer (if unaligned, otherwise destination buffer is
35 * used directly) upon stop() call.
36 */
37#define GEN_BB_RW	(GEN_BB_READ | GEN_BB_WRITE)
38
39struct bounce_buffer {
40	/* Copy of data parameter passed to start() */
41	void *user_buffer;
42	/*
43	 * DMA-aligned buffer. This field is always set to the value that
44	 * should be used for DMA; either equal to .user_buffer, or to a
45	 * freshly allocated aligned buffer.
46	 */
47	void *bounce_buffer;
48	/* Copy of len parameter passed to start() */
49	size_t len;
50	/* DMA-aligned buffer length */
51	size_t len_aligned;
52	/* Copy of flags parameter passed to start() */
53	unsigned int flags;
54};
55
56/**
57 * bounce_buffer_start() -- Start the bounce buffer session
58 * state:	stores state passed between bounce_buffer_{start,stop}
59 * data:	pointer to buffer to be aligned
60 * len:		length of the buffer
61 * flags:	flags describing the transaction, see above.
62 */
63int bounce_buffer_start(struct bounce_buffer *state, void *data,
64			size_t len, unsigned int flags);
65
66/**
67 * bounce_buffer_start() -- Start the bounce buffer session with external align check function
68 * state:	stores state passed between bounce_buffer_{start,stop}
69 * data:	pointer to buffer to be aligned
70 * len:		length of the buffer
71 * flags:	flags describing the transaction, see above.
72 * alignment:	alignment of the newly allocated bounce buffer
73 * addr_is_aligned: function for checking the alignment instead of the default one
74 */
75int bounce_buffer_start_extalign(struct bounce_buffer *state, void *data,
76				 size_t len, unsigned int flags,
77				 size_t alignment,
78				 int (*addr_is_aligned)(struct bounce_buffer *state));
79
80/**
81 * bounce_buffer_stop() -- Finish the bounce buffer session
82 * state:	stores state passed between bounce_buffer_{start,stop}
83 */
84int bounce_buffer_stop(struct bounce_buffer *state);
85
86#endif
87