1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
/*
* Copyright (c) 2016, NVIDIA CORPORATION.
*
* SPDX-License-Identifier: GPL-2.0
*/
#ifndef _MAILBOX_CLIENT_H
#define _MAILBOX_CLIENT_H
/**
* A mailbox is a hardware mechanism for transferring small fixed-size messages
* and/or notifications between the CPU on which U-Boot runs and some other
* device such as an auxiliary CPU running firmware or a hardware module.
*
* Data transfer is optional; a mailbox may consist solely of a notification
* mechanism. When data transfer is implemented, it is via HW registers or
* FIFOs, rather than via RAM-based buffers. The mailbox API generally
* implements any communication protocol enforced solely by hardware, and
* leaves any higher-level protocols to other layers.
*
* A mailbox channel is a bi-directional mechanism that can send a message or
* notification to a single specific remote entity, and receive messages or
* notifications from that entity. The size, content, and format of such
* messages is defined by the mailbox implementation, or the remote entity with
* which it communicates; there is no general standard at this API level.
*
* A driver that implements UCLASS_MAILBOX is a mailbox provider. A provider
* will often implement multiple separate mailbox channels, since the hardware
* it manages often has this capability. mailbox_uclass.h describes the
* interface which mailbox providers must implement.
*
* Mailbox consumers/clients generate and send, or receive and process,
* messages. This header file describes the API used by clients.
*/
struct udevice;
/**
* struct mbox_chan - A handle to a single mailbox channel.
*
* Clients provide storage for channels. The content of the channel structure
* is managed solely by the mailbox API and mailbox drivers. A mailbox channel
* is initialized by "get"ing the mailbox. The channel struct is passed to all
* other mailbox APIs to identify which mailbox to operate upon.
*
* @dev: The device which implements the mailbox.
* @id: The mailbox channel ID within the provider.
*
* Currently, the mailbox API assumes that a single integer ID is enough to
* identify and configure any mailbox channel for any mailbox provider. If this
* assumption becomes invalid in the future, the struct could be expanded to
* either (a) add more fields to allow mailbox providers to store additional
* information, or (b) replace the id field with an opaque pointer, which the
* provider would dynamically allocated during its .of_xlate op, and process
* during is .request op. This may require the addition of an extra op to clean
* up the allocation.
*/
struct mbox_chan {
struct udevice *dev;
/*
* Written by of_xlate. We assume a single id is enough for now. In the
* future, we might add more fields here.
*/
unsigned long id;
};
/**
* mbox_get_by_index - Get/request a mailbox by integer index
*
* This looks up and requests a mailbox channel. The index is relative to the
* client device; each device is assumed to have n mailbox channels associated
* with it somehow, and this function finds and requests one of them. The
* mapping of client device channel indices to provider channels may be via
* device-tree properties, board-provided mapping tables, or some other
* mechanism.
*
* @dev: The client device.
* @index: The index of the mailbox channel to request, within the
* client's list of channels.
* @chan A pointer to a channel object to initialize.
* @return 0 if OK, or a negative error code.
*/
int mbox_get_by_index(struct udevice *dev, int index, struct mbox_chan *chan);
/**
* mbox_get_by_name - Get/request a mailbox by name
*
* This looks up and requests a mailbox channel. The name is relative to the
* client device; each device is assumed to have n mailbox channels associated
* with it somehow, and this function finds and requests one of them. The
* mapping of client device channel names to provider channels may be via
* device-tree properties, board-provided mapping tables, or some other
* mechanism.
*
* @dev: The client device.
* @name: The name of the mailbox channel to request, within the client's
* list of channels.
* @chan A pointer to a channel object to initialize.
* @return 0 if OK, or a negative error code.
*/
int mbox_get_by_name(struct udevice *dev, const char *name,
struct mbox_chan *chan);
/**
* mbox_free - Free a previously requested mailbox channel.
*
* @chan: A channel object that was previously successfully requested by
* calling mbox_get_by_*().
* @return 0 if OK, or a negative error code.
*/
int mbox_free(struct mbox_chan *chan);
/**
* mbox_send - Send a message over a mailbox channel
*
* This function will send a message to the remote entity. It may return before
* the remote entity has received and/or processed the message.
*
* @chan: A channel object that was previously successfully requested by
* calling mbox_get_by_*().
* @data: A pointer to the message to transfer. The format and size of
* the memory region pointed at by @data is determined by the
* mailbox provider. Providers that solely transfer notifications
* will ignore this parameter.
* @return 0 if OK, or a negative error code.
*/
int mbox_send(struct mbox_chan *chan, const void *data);
/**
* mbox_recv - Receive any available message from a mailbox channel
*
* This function will wait (up to the specified @timeout_us) for a message to
* be sent by the remote entity, and write the content of any such message
* into a caller-provided buffer.
*
* @chan: A channel object that was previously successfully requested by
* calling mbox_get_by_*().
* @data: A pointer to the buffer to receive the message. The format and
* size of the memory region pointed at by @data is determined by
* the mailbox provider. Providers that solely transfer
* notifications will ignore this parameter.
* @timeout_us: The maximum time to wait for a message to be available, in
* micro-seconds. A value of 0 does not wait at all.
* @return 0 if OK, -ENODATA if no message was available, or a negative error
* code.
*/
int mbox_recv(struct mbox_chan *chan, void *data, ulong timeout_us);
#endif
|
