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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
|
/* SPDX-License-Identifier: GPL-2.0+ */
/*
* (C) Copyright 2012,2015 Stephen Warren
*/
#ifndef _BCM2835_MBOX_H
#define _BCM2835_MBOX_H
#include <linux/compiler.h>
#include <asm/arch/base.h>
/*
* The BCM2835 SoC contains (at least) two CPUs; the VideoCore (a/k/a "GPU")
* and the ARM CPU. The ARM CPU is often thought of as the main CPU.
* However, the VideoCore actually controls the initial SoC boot, and hides
* much of the hardware behind a protocol. This protocol is transported
* using the SoC's mailbox hardware module.
*
* The mailbox hardware supports passing 32-bit values back and forth.
* Presumably by software convention of the firmware, the bottom 4 bits of the
* value are used to indicate a logical channel, and the upper 28 bits are the
* actual payload. Various channels exist using these simple raw messages. See
* https://github.com/raspberrypi/firmware/wiki/Mailboxes for a list. As an
* example, the messages on the power management channel are a bitmask of
* devices whose power should be enabled.
*
* The property mailbox channel passes messages that contain the (16-byte
* aligned) ARM physical address of a memory buffer. This buffer is passed to
* the VC for processing, is modified in-place by the VC, and the address then
* passed back to the ARM CPU as the response mailbox message to indicate
* request completion. The buffers have a generic and extensible format; each
* buffer contains a standard header, a list of "tags", and a terminating zero
* entry. Each tag contains an ID indicating its type, and length fields for
* generic parsing. With some limitations, an arbitrary set of tags may be
* combined together into a single message buffer. This file defines structs
* representing the header and many individual tag layouts and IDs.
*/
/* Raw mailbox HW */
#define BCM2835_MBOX_PHYSADDR rpi_mbox_base
struct bcm2835_mbox_regs {
u32 read;
u32 rsvd0[5];
u32 mail0_status;
u32 mail0_config;
u32 write;
u32 rsvd1[5];
u32 mail1_status;
u32 mail1_config;
};
#define BCM2835_MBOX_STATUS_WR_FULL 0x80000000
#define BCM2835_MBOX_STATUS_RD_EMPTY 0x40000000
/* Lower 4-bits are channel ID */
#define BCM2835_CHAN_MASK 0xf
#define BCM2835_MBOX_PACK(chan, data) (((data) & (~BCM2835_CHAN_MASK)) | \
(chan & BCM2835_CHAN_MASK))
#define BCM2835_MBOX_UNPACK_CHAN(val) ((val) & BCM2835_CHAN_MASK)
#define BCM2835_MBOX_UNPACK_DATA(val) ((val) & (~BCM2835_CHAN_MASK))
/* Property mailbox buffer structures */
#define BCM2835_MBOX_PROP_CHAN 8
/* All message buffers must start with this header */
struct bcm2835_mbox_hdr {
u32 buf_size;
u32 code;
};
#define BCM2835_MBOX_REQ_CODE 0
#define BCM2835_MBOX_RESP_CODE_SUCCESS 0x80000000
#define BCM2835_MBOX_INIT_HDR(_m_) { \
memset((_m_), 0, sizeof(*(_m_))); \
(_m_)->hdr.buf_size = sizeof(*(_m_)); \
(_m_)->hdr.code = 0; \
(_m_)->end_tag = 0; \
}
/*
* A message buffer contains a list of tags. Each tag must also start with
* a standardized header.
*/
struct bcm2835_mbox_tag_hdr {
u32 tag;
u32 val_buf_size;
u32 val_len;
};
#define BCM2835_MBOX_INIT_TAG(_t_, _id_) { \
(_t_)->tag_hdr.tag = BCM2835_MBOX_TAG_##_id_; \
(_t_)->tag_hdr.val_buf_size = sizeof((_t_)->body); \
(_t_)->tag_hdr.val_len = sizeof((_t_)->body.req); \
}
#define BCM2835_MBOX_INIT_TAG_NO_REQ(_t_, _id_) { \
(_t_)->tag_hdr.tag = BCM2835_MBOX_TAG_##_id_; \
(_t_)->tag_hdr.val_buf_size = sizeof((_t_)->body); \
(_t_)->tag_hdr.val_len = 0; \
}
/* When responding, the VC sets this bit in val_len to indicate a response */
#define BCM2835_MBOX_TAG_VAL_LEN_RESPONSE 0x80000000
/*
* Below we define the ID and struct for many possible tags. This header only
* defines individual tag structs, not entire message structs, since in
* general an arbitrary set of tags may be combined into a single message.
* Clients of the mbox API are expected to define their own overall message
* structures by combining the header, a set of tags, and a terminating
* entry. For example,
*
* struct msg {
* struct bcm2835_mbox_hdr hdr;
* struct bcm2835_mbox_tag_get_arm_mem get_arm_mem;
* ... perhaps other tags here ...
* u32 end_tag;
* };
*/
#define BCM2835_MBOX_TAG_GET_BOARD_REV 0x00010002
struct bcm2835_mbox_tag_get_board_rev {
struct bcm2835_mbox_tag_hdr tag_hdr;
union {
struct {
} req;
struct {
u32 rev;
} resp;
} body;
};
#define BCM2835_MBOX_TAG_GET_MAC_ADDRESS 0x00010003
struct bcm2835_mbox_tag_get_mac_address {
struct bcm2835_mbox_tag_hdr tag_hdr;
union {
struct {
} req;
struct {
u8 mac[6];
u8 pad[2];
} resp;
} body;
};
#define BCM2835_MBOX_TAG_GET_BOARD_SERIAL 0x00010004
struct bcm2835_mbox_tag_get_board_serial {
struct bcm2835_mbox_tag_hdr tag_hdr;
union {
struct __packed {
u64 serial;
} resp;
} body;
};
#define BCM2835_MBOX_TAG_GET_ARM_MEMORY 0x00010005
struct bcm2835_mbox_tag_get_arm_mem {
struct bcm2835_mbox_tag_hdr tag_hdr;
union {
struct {
} req;
struct {
u32 mem_base;
u32 mem_size;
} resp;
} body;
};
#define BCM2835_MBOX_POWER_DEVID_SDHCI 0
#define BCM2835_MBOX_POWER_DEVID_UART0 1
#define BCM2835_MBOX_POWER_DEVID_UART1 2
#define BCM2835_MBOX_POWER_DEVID_USB_HCD 3
#define BCM2835_MBOX_POWER_DEVID_I2C0 4
#define BCM2835_MBOX_POWER_DEVID_I2C1 5
#define BCM2835_MBOX_POWER_DEVID_I2C2 6
#define BCM2835_MBOX_POWER_DEVID_SPI 7
#define BCM2835_MBOX_POWER_DEVID_CCP2TX 8
#define BCM2835_MBOX_POWER_STATE_RESP_ON (1 << 0)
/* Device doesn't exist */
#define BCM2835_MBOX_POWER_STATE_RESP_NODEV (1 << 1)
#define BCM2835_MBOX_TAG_GET_POWER_STATE 0x00020001
struct bcm2835_mbox_tag_get_power_state {
struct bcm2835_mbox_tag_hdr tag_hdr;
union {
struct {
u32 device_id;
} req;
struct {
u32 device_id;
u32 state;
} resp;
} body;
};
#define BCM2835_MBOX_TAG_SET_POWER_STATE 0x00028001
#define BCM2835_MBOX_SET_POWER_STATE_REQ_ON (1 << 0)
#define BCM2835_MBOX_SET_POWER_STATE_REQ_WAIT (1 << 1)
struct bcm2835_mbox_tag_set_power_state {
struct bcm2835_mbox_tag_hdr tag_hdr;
union {
struct {
u32 device_id;
u32 state;
} req;
struct {
u32 device_id;
u32 state;
} resp;
} body;
};
#define BCM2835_MBOX_TAG_GET_CLOCK_RATE 0x00030002
#define BCM2835_MBOX_TAG_GET_MAX_CLOCK_RATE 0x00030004
#define BCM2835_MBOX_TAG_GET_MIN_CLOCK_RATE 0x00030007
#define BCM2835_MBOX_CLOCK_ID_EMMC 1
#define BCM2835_MBOX_CLOCK_ID_UART 2
#define BCM2835_MBOX_CLOCK_ID_ARM 3
#define BCM2835_MBOX_CLOCK_ID_CORE 4
#define BCM2835_MBOX_CLOCK_ID_V3D 5
#define BCM2835_MBOX_CLOCK_ID_H264 6
#define BCM2835_MBOX_CLOCK_ID_ISP 7
#define BCM2835_MBOX_CLOCK_ID_SDRAM 8
#define BCM2835_MBOX_CLOCK_ID_PIXEL 9
#define BCM2835_MBOX_CLOCK_ID_PWM 10
#define BCM2835_MBOX_CLOCK_ID_EMMC2 12
struct bcm2835_mbox_tag_get_clock_rate {
struct bcm2835_mbox_tag_hdr tag_hdr;
union {
struct {
u32 clock_id;
} req;
struct {
u32 clock_id;
u32 rate_hz;
} resp;
} body;
};
#define BCM2835_MBOX_TAG_SET_SDHOST_CLOCK 0x00038042
struct bcm2835_mbox_tag_set_sdhost_clock {
struct bcm2835_mbox_tag_hdr tag_hdr;
union {
struct {
u32 rate_hz;
} req;
struct {
u32 rate_hz;
u32 rate_1;
u32 rate_2;
} resp;
} body;
};
#define BCM2835_MBOX_TAG_ALLOCATE_BUFFER 0x00040001
struct bcm2835_mbox_tag_allocate_buffer {
struct bcm2835_mbox_tag_hdr tag_hdr;
union {
struct {
u32 alignment;
} req;
struct {
u32 fb_address;
u32 fb_size;
} resp;
} body;
};
#define BCM2835_MBOX_TAG_RELEASE_BUFFER 0x00048001
struct bcm2835_mbox_tag_release_buffer {
struct bcm2835_mbox_tag_hdr tag_hdr;
union {
struct {
} req;
struct {
} resp;
} body;
};
#define BCM2835_MBOX_TAG_BLANK_SCREEN 0x00040002
struct bcm2835_mbox_tag_blank_screen {
struct bcm2835_mbox_tag_hdr tag_hdr;
union {
struct {
/* bit 0 means on, other bots reserved */
u32 state;
} req;
struct {
u32 state;
} resp;
} body;
};
/* Physical means output signal */
#define BCM2835_MBOX_TAG_GET_PHYSICAL_W_H 0x00040003
#define BCM2835_MBOX_TAG_TEST_PHYSICAL_W_H 0x00044003
#define BCM2835_MBOX_TAG_SET_PHYSICAL_W_H 0x00048003
struct bcm2835_mbox_tag_physical_w_h {
struct bcm2835_mbox_tag_hdr tag_hdr;
union {
/* req not used for get */
struct {
u32 width;
u32 height;
} req;
struct {
u32 width;
u32 height;
} resp;
} body;
};
/* Virtual means display buffer */
#define BCM2835_MBOX_TAG_GET_VIRTUAL_W_H 0x00040004
#define BCM2835_MBOX_TAG_TEST_VIRTUAL_W_H 0x00044004
#define BCM2835_MBOX_TAG_SET_VIRTUAL_W_H 0x00048004
struct bcm2835_mbox_tag_virtual_w_h {
struct bcm2835_mbox_tag_hdr tag_hdr;
union {
/* req not used for get */
struct {
u32 width;
u32 height;
} req;
struct {
u32 width;
u32 height;
} resp;
} body;
};
#define BCM2835_MBOX_TAG_GET_DEPTH 0x00040005
#define BCM2835_MBOX_TAG_TEST_DEPTH 0x00044005
#define BCM2835_MBOX_TAG_SET_DEPTH 0x00048005
struct bcm2835_mbox_tag_depth {
struct bcm2835_mbox_tag_hdr tag_hdr;
union {
/* req not used for get */
struct {
u32 bpp;
} req;
struct {
u32 bpp;
} resp;
} body;
};
#define BCM2835_MBOX_TAG_GET_PIXEL_ORDER 0x00040006
#define BCM2835_MBOX_TAG_TEST_PIXEL_ORDER 0x00044006
#define BCM2835_MBOX_TAG_SET_PIXEL_ORDER 0x00048006
#define BCM2835_MBOX_PIXEL_ORDER_BGR 0
#define BCM2835_MBOX_PIXEL_ORDER_RGB 1
struct bcm2835_mbox_tag_pixel_order {
struct bcm2835_mbox_tag_hdr tag_hdr;
union {
/* req not used for get */
struct {
u32 order;
} req;
struct {
u32 order;
} resp;
} body;
};
#define BCM2835_MBOX_TAG_GET_ALPHA_MODE 0x00040007
#define BCM2835_MBOX_TAG_TEST_ALPHA_MODE 0x00044007
#define BCM2835_MBOX_TAG_SET_ALPHA_MODE 0x00048007
#define BCM2835_MBOX_ALPHA_MODE_0_OPAQUE 0
#define BCM2835_MBOX_ALPHA_MODE_0_TRANSPARENT 1
#define BCM2835_MBOX_ALPHA_MODE_IGNORED 2
struct bcm2835_mbox_tag_alpha_mode {
struct bcm2835_mbox_tag_hdr tag_hdr;
union {
/* req not used for get */
struct {
u32 alpha;
} req;
struct {
u32 alpha;
} resp;
} body;
};
#define BCM2835_MBOX_TAG_GET_PITCH 0x00040008
struct bcm2835_mbox_tag_pitch {
struct bcm2835_mbox_tag_hdr tag_hdr;
union {
struct {
} req;
struct {
u32 pitch;
} resp;
} body;
};
/* Offset of display window within buffer */
#define BCM2835_MBOX_TAG_GET_VIRTUAL_OFFSET 0x00040009
#define BCM2835_MBOX_TAG_TEST_VIRTUAL_OFFSET 0x00044009
#define BCM2835_MBOX_TAG_SET_VIRTUAL_OFFSET 0x00048009
struct bcm2835_mbox_tag_virtual_offset {
struct bcm2835_mbox_tag_hdr tag_hdr;
union {
/* req not used for get */
struct {
u32 x;
u32 y;
} req;
struct {
u32 x;
u32 y;
} resp;
} body;
};
#define BCM2835_MBOX_TAG_GET_OVERSCAN 0x0004000a
#define BCM2835_MBOX_TAG_TEST_OVERSCAN 0x0004400a
#define BCM2835_MBOX_TAG_SET_OVERSCAN 0x0004800a
struct bcm2835_mbox_tag_overscan {
struct bcm2835_mbox_tag_hdr tag_hdr;
union {
/* req not used for get */
struct {
u32 top;
u32 bottom;
u32 left;
u32 right;
} req;
struct {
u32 top;
u32 bottom;
u32 left;
u32 right;
} resp;
} body;
};
#define BCM2835_MBOX_TAG_GET_PALETTE 0x0004000b
struct bcm2835_mbox_tag_get_palette {
struct bcm2835_mbox_tag_hdr tag_hdr;
union {
struct {
} req;
struct {
u32 data[1024];
} resp;
} body;
};
#define BCM2835_MBOX_TAG_TEST_PALETTE 0x0004400b
struct bcm2835_mbox_tag_test_palette {
struct bcm2835_mbox_tag_hdr tag_hdr;
union {
struct {
u32 offset;
u32 num_entries;
u32 data[256];
} req;
struct {
u32 is_invalid;
} resp;
} body;
};
#define BCM2835_MBOX_TAG_SET_PALETTE 0x0004800b
struct bcm2835_mbox_tag_set_palette {
struct bcm2835_mbox_tag_hdr tag_hdr;
union {
struct {
u32 offset;
u32 num_entries;
u32 data[256];
} req;
struct {
u32 is_invalid;
} resp;
} body;
};
#define BCM2835_MBOX_TAG_NOTIFY_XHCI_RESET 0x00030058
struct bcm2835_mbox_tag_pci_dev_addr {
struct bcm2835_mbox_tag_hdr tag_hdr;
union {
struct {
u32 dev_addr;
} req;
struct {
} resp;
} body;
};
/*
* Pass a raw u32 message to the VC, and receive a raw u32 back.
*
* Returns 0 for success, any other value for error.
*/
int bcm2835_mbox_call_raw(u32 chan, u32 send, u32 *recv);
/*
* Pass a complete property-style buffer to the VC, and wait until it has
* been processed.
*
* This function expects a pointer to the mbox_hdr structure in an attempt
* to ensure some degree of type safety. However, some number of tags and
* a termination value are expected to immediately follow the header in
* memory, as required by the property protocol.
*
* Each struct bcm2835_mbox_hdr passed must be allocated with
* ALLOC_CACHE_ALIGN_BUFFER(x, y, z) to ensure proper cache flush/invalidate.
*
* Returns 0 for success, any other value for error.
*/
int bcm2835_mbox_call_prop(u32 chan, struct bcm2835_mbox_hdr *buffer);
#endif
|