Document the bcm_host helper functions

[P33M]

For programs wanting to poke peripheral addresses directly (for lack of a better interface), they need to know where in the virtual memory map the peripheral bus segment has been placed. This used to be tied to the platform (or rather had the same address since day 0), now is variable between Pi1 and Pi2.

Perhaps we need a one-pager in the hardware section detailing how to use this api:

https://github.com/raspberrypi/firmware/blob/master/opt/vc/include/bcm_host.h

[ghollingworth]

:)

[ebenupton]

Jonathan - can you propose some text, and where you think it should be located in the documentation?

[JamesH65]

Hi @P33M, any news on this?

[JamesH65]

@P33M @popcornmix If either of you guys can give me a leg up on how this stuff works and why it's needed, I'm happy to write the documentation for it. Would be nice to get this 2 year old issue out of the way!

[popcornmix]

The code is here:
https://github.com/raspberrypi/userland/blob/master/host_applications/linux/libs/bcm_host/bcm_host.c#L150-L166
They just read from device-tree (falling back to hard-coded Pi1 addresses if not available) the addresses needed for accessing sdram or peripherals from arm.

bcm_host_get_peripheral_address
Gets the arm side physical address of where peripherals are mapped.
Will be 0x20000000 on Pi1 and 0x3f000000 on Pi2

bcm_host_get_peripheral_size
Gets the size of peripherals space
Will always be 0x01000000

bcm_host_get_sdram_address
Gets the bus address of usual alias of sdram.
Will be 0x40000000 on Pi1 (GPU L2 cached) and 0xC0000000 on Pi2 (uncached).

These are of interest to very few users - i.e. those who want to mmap peripherals to access without using a kernel driver.

[JamesH65]

@popcornmix Does this read OK for the bcm stuff? Which library do you need to build in to get this library, just bcmhost?

[JamesH65]

Sorry, I should have linked to the PR. #623