diff --git a/host_applications/linux/apps/dtmerge/CMakeLists.txt b/host_applications/linux/apps/dtmerge/CMakeLists.txt index d17369773..d3f7e36c2 100755 --- a/host_applications/linux/apps/dtmerge/CMakeLists.txt +++ b/host_applications/linux/apps/dtmerge/CMakeLists.txt @@ -18,3 +18,4 @@ add_executable(dtmerge dtmerge.c) target_link_libraries(dtmerge dtovl) install(TARGETS dtmerge RUNTIME DESTINATION bin) +install(FILES dtmerge.1 DESTINATION man/man1) diff --git a/host_applications/linux/apps/dtmerge/dtmerge.1 b/host_applications/linux/apps/dtmerge/dtmerge.1 new file mode 100644 index 000000000..5b240ebf1 --- /dev/null +++ b/host_applications/linux/apps/dtmerge/dtmerge.1 @@ -0,0 +1,72 @@ +.TH DTMERGE 1 +. +.SH NAME +dtmerge \- merge an overlay or parameters into a base device-tree +. +. +.SH SYNOPSIS +.SY dtmerge +.OP \-d +.I base-dtb +.I merged-dtb +.I overlay-dtb +.RI [ param=val \|.\|.\|.] +.YS +. +.SY dtmerge +.B \-h +.YS +. +. +.SH DESCRIPTION +.B dtmerge +is a command line utility for merging overlays and/or device-tree parameters +with a base device-tree. +See +.B [DTREE] +for more information. +. +.PP +The base device-tree (in dtb format) is always specified as the first +(non-option) argument. +The second argument is the output filename, which will also be in dtb format. +The third argument provides the name of the overlay to merge into the base +tree. +If this is "-" then no overlay is used and the utility will simply customize +the base tree with any parameters given. +. +. +.SH OPTIONS +. +.TP +.BR \-d +Show debug output during operation. +. +.TP +.BR \-h +Displays help on the application. +. +. +.SH EXAMPLES +. +.TP +.B dtmerge /boot/bcm2711-rpi-4-b.dtb out.dtb - spi=on i2c=on +Produce a device-tree for the Raspberry Pi 4 in "out.dtb" which has the SPI and +I2C interfaces activated. +. +.TP +.B dtmerge /boot/bcm2710-rpi-3-b-plus.dtb out.dtb /boot/overlays/gpio-shutdown.dtbo +Produce a device-tree for the Raspberry Pi 3+ in "out.dtb" which includes the +GPIO shutdown overlay (with all parameters set to their default). +. +. +.SH SEE ALSO +.BR dtoverlay (1), +.BR dtparam (1), +.B [DTREE] +. +. +.SH REFERENCES +.TP +.B [DTREE] +https://www.raspberrypi.org/documentation/configuration/device-tree.md diff --git a/host_applications/linux/apps/dtoverlay/CMakeLists.txt b/host_applications/linux/apps/dtoverlay/CMakeLists.txt index dd48d831b..97bcadcf9 100755 --- a/host_applications/linux/apps/dtoverlay/CMakeLists.txt +++ b/host_applications/linux/apps/dtoverlay/CMakeLists.txt @@ -17,9 +17,11 @@ include_directories ( add_executable(dtoverlay dtoverlay_main.c utils.c) target_link_libraries(dtoverlay dtovl) install(TARGETS dtoverlay RUNTIME DESTINATION bin) +install(FILES dtoverlay.1 DESTINATION man/man1) add_custom_command(TARGET dtoverlay POST_BUILD COMMAND ln;-sf;dtoverlay;dtparam) install(FILES ${CMAKE_CURRENT_BINARY_DIR}/dtparam DESTINATION bin) +install(FILES dtparam.1 DESTINATION man/man1) set(DTOVERLAY_SCRIPTS dtoverlay-pre dtoverlay-post) install(PROGRAMS ${DTOVERLAY_SCRIPTS} DESTINATION bin) diff --git a/host_applications/linux/apps/dtoverlay/dtoverlay.1 b/host_applications/linux/apps/dtoverlay/dtoverlay.1 new file mode 100644 index 000000000..5d58145d1 --- /dev/null +++ b/host_applications/linux/apps/dtoverlay/dtoverlay.1 @@ -0,0 +1,153 @@ +.TH DTOVERLAY 1 +. +.SH NAME +dtoverlay \- load a device-tree overlay +. +. +.SH SYNOPSIS +.SY dtoverlay +.OP \-d dir +.OP \-p string +.OP \-v +.OP \-D +.OP \-r +.OP \-R +.OP \-l +.OP \-a +.RI [ overlay " [" param=val \|.\|.\|.]] +.YS +. +.SY dtoverlay +.B \-h +.RI [ overlay " [" param ]] +.YS +. +. +.SH DESCRIPTION +.B dtoverlay +is a command line utility for manipulating the system's runtime device-tree by +adding or removing overlays. +It can also customize the base device-tree or overlays by setting parameters +within them. +See +.B [DTREE] +for more information. +. +.PP +By default, without the +.B -r +or +.B -R +options, the application adds the specified overlay. Manipulation of +active device-tree overlays usually requires root privileges. +. +. +.SH OPTIONS +. +.TP +.BR \-a +Lists all defined device-tree overlays, placing a "*" next to those that are +currently loaded. +. +.TP +.BR \-d " \fIdir\fR" +Specifies an alternate location path from which to load overlays. The utility +defaults to "/boot/overlays" or "/flash/overlays". +. +.TP +.BR \-D +Dry-run; prepares the specified overlay but doesn't apply it. The resulting +prepared overlay is saved as "dry-run.dtbo". +. +.TP +.BR \-h [\fIoverlay\fR] [\fIparam\fR] +If given without +.I overlay +or +.I param +displays help on the application overall. If +.I overlay +is specified, prints help on that overlay. Finally, if +.I param +is also specified, prints help on that parameter of the overlay. To query +parameters on the base overlay, specify "dtparam" as the +.IR overlay . +. +.TP +.BR \-l +Lists all currently loaded device-tree overlays, in the order they were loaded. +This also specifies the index of each overlay. +. +.TP +.BR \-p " \fIstring\fR" +Override the platform's "compatible" string, normally read from +"/proc/device-tree/compatible". This is used with the overlay map to determine +which platform-specific overlay to read (if necessary). +. +.TP +.BR \-r +Remove overlay. With this option, the utility will remove the specified +overlay. If no overlay is given, the last overlay loaded will be removed. +Overlays can be specified by name or by index. +. +.TP +.BR \-R +Remove the specified overlay, and all subsequent overlays that were loaded +after it. If no overlay is given, all overlays will be removed. Overlays can +be specified by name or by index. +. +.TP +.BR \-v +Verbose operation; the utility will produce more output. +. +. +.SH EXAMPLES +. +.TP +.B sudo dtoverlay w1-gpio +Load the w1-gpio overlay (to enable Dallas 1-Wire on GPIO4). Note that root +privileges are usually required for manipulating the device-tree overlays +(hence, sudo in the example). +. +.TP +.B dtoverlay -l +Show the loaded overlays. +. +.TP +.B sudo dtoverlay -r +Remove the last loaded overlay. +. +.TP +.B sudo dtoverlay gpio-shutdown gpio_pin=7 active_low=0 gpio_pull=down +Load the gpio-shutdown overlay specifying that it should pull GPIO7 down and +monitor it for a rising edge to initiate shutdown. +. +.TP +.B dtoverlay -h gpio-shutdown +Display help for the gpio-shutdown overlay +. +.TP +.B sudo dtoverlay -r gpio-shutdown +Remove the gpio-shutdown overlay, wherever it is in the load order. +. +. +.SH HOOKS +.B dtoverlay +attempts to call two executables (shell scripts by default) during its +operation: +.B dtoverlay-pre +prior to making device-tree modifications, and +.B dtoverlay-post +afterwards. Each executable is optional and will be ignored if not present. +. +. +.SH SEE ALSO +.BR dtparam (1), +.BR dtmerge (1), +.B [DTREE] +. +. +.SH REFERENCES +.TP +.B [DTREE] +https://www.raspberrypi.org/documentation/configuration/device-tree.md diff --git a/host_applications/linux/apps/dtoverlay/dtparam.1 b/host_applications/linux/apps/dtoverlay/dtparam.1 new file mode 100644 index 000000000..51c935f70 --- /dev/null +++ b/host_applications/linux/apps/dtoverlay/dtparam.1 @@ -0,0 +1,66 @@ +.TH DTPARAM 1 +. +.SH NAME +dtparam \- mainpulate parameters of the base device-tree +. +. +.SH SYNOPSIS +.SY dtparam +.RI [ param=val \|.\|.\|.] +.YS +. +.SY dtparam +.B \-h +.RI [ param ] +.YS +. +. +.SH DESCRIPTION +.B dtparam +is a command line utility for manipulating the base device-tree's parameters. +For example, it can be used to enable the SPI or I2C interfaces at runtime +without rebooting. +If +.B dtparam +is run without any argument, it prints the names of all base device-tree +parameters and their description. +. +. +.SH OPTIONS +. +.TP +.BR \-h " [\fIparam\fR]" +If given without +.I param +displays help on the application overall. If +.I param +is specified, prints help about that parameter in the base device-tree. +. +. +.SH EXAMPLES +. +.TP +.B sudo dtparam spi=on +Enable the SPI interface on the GPIO header. Note that root privileges are +usually required for manipulating the base device-tree (hence, sudo in the +example). +. +.TP +.B dtparam -h spi +Print help about the "spi" parameter. +. +.TP +.B sudo dtparam audio=off +Disable the audio output. +. +. +.SH SEE ALSO +.BR dtoverlay (1), +.BR dtmerge (1), +.B [DTREE] +. +. +.SH REFERENCES +.TP +.B [DTREE] +https://www.raspberrypi.org/documentation/configuration/device-tree.md diff --git a/host_applications/linux/apps/gencmd/CMakeLists.txt b/host_applications/linux/apps/gencmd/CMakeLists.txt index f95d1a1b7..0c2c32a4c 100644 --- a/host_applications/linux/apps/gencmd/CMakeLists.txt +++ b/host_applications/linux/apps/gencmd/CMakeLists.txt @@ -17,4 +17,4 @@ include_directories( ../../../.. add_executable(vcgencmd gencmd.c) target_link_libraries(vcgencmd vcos vchiq_arm vchostif) install(TARGETS vcgencmd RUNTIME DESTINATION bin) - +install(FILES vcgencmd.1 DESTINATION man/man1) diff --git a/host_applications/linux/apps/gencmd/vcgencmd.1 b/host_applications/linux/apps/gencmd/vcgencmd.1 new file mode 100644 index 000000000..ec424b080 --- /dev/null +++ b/host_applications/linux/apps/gencmd/vcgencmd.1 @@ -0,0 +1,303 @@ +.TH VCGENCMD 1 +. +.SH NAME +vcgencmd \- query the VideoCore for information +. +. +.SH SYNOPSIS +.SY vcgencmd +.OP \-t +.IR command \ [ params ] +.YS +. +.SY vcgencmd +.B \-h +.SY vcgencmd +.B \-\-help +.YS +. +. +.SH DESCRIPTION +.B vcgencmd +is a command line utility that can get various pieces of information +from the VideoCore GPU on the Raspberry Pi. +. +. +.SH OPTIONS +.TP +.B \-t +Time how long the command takes to complete +. +.TP +.BR \-h ", " \-\-help +Show this information +. +. +.SH COMMANDS +To get a list of all the commands that +.B vcgencmd +supports, type +.IR "vcgencmd\ commands" . +Some of the more useful commands are described below. +. +.TP +.BI vcos \ sub-command +The +.B vcos +command has a number of sub-commands: +.RS +.TP +.B version +Displays the build date and version of the firmware on the VideoCore. +.TP +.B log status +Displays the error log status of the various VideoCore software areas. +.RE +. +.TP +.B version +Displays the build date and version of the firmware on the VideoCore. +. +.TP +.B get_camera +Displays the enabled and detected state of the official camera. 1 means yes, 0 +means no. Whilst all firmware (except cutdown versions) will support the camera, +this support needs to be enabled by using the +.I start_x +boot option +.BR [BOOT] . +. +.TP +.B get_throttled +Returns the throttled state of the system. This is a bit pattern - a bit being +set indicates the following meanings: +.TS +tab(|); +l l . +Bit|Meaning +\_|\_ +.T& +n l . +0|Under-voltage detected +1|Arm frequency capped +2|Currently throttled +3|Soft temperature limit active +16|Under-voltage has occurred +17|Arm frequency capping has occurred +18|Throttling has occurred +19|Soft temperature limit has occurred +.TE +.IP +A value of zero indicates that none of the above conditions is true. +.IP +To find if one of these bits has been set, convert the value returned to binary, +then number each bit along the top. You can then see which bits are set. For +example: +.IP +.EX +0x50000 = 0101 0000 0000 0000 0000 +.EE +.IP +Adding the bit numbers along the top we get: +.TS +tab( ); +n n n n n n n n n n n n n n n n n n n . +19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 +0 1 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 +.TE +.IP +From this we can see that bits 18 and 16 are set, indicating that the Pi has +previously been throttled due to under-voltage, but is not currently throttled +for any reason. +. +.TP +.B measure_temp +Returns the temperature of the SoC as measured by the on-board temperature +sensor. +. +.TP +.BI measure_clock \ clock +This returns the current frequency of the specified clock. The options are: +.TS +tab(|); +l l . +Clock|Description +\_|\_ +arm|ARM cores +core|VC4 scaler cores +h264|H.264 block +isp|Image Signal Processor +v3d|3D block +uart|UART +pwm|PWM block (analog audio output) +emmc|SD card interface +pixel|Pixel valve +vec|Analog video encoder +hdmi|HDMI +dpi|Display Peripheral Interface +.TE +.IP +For example, +.IR "vcgencmd measure_clock arm" . +. +.TP +.BI measure_volts \ block +Displays the current voltages used by the specific block. +.TS +tab(|); +l l . +Block|Description +\_|\_ +core|VC4 core voltage +sdram_c| +sdram_i| +sdram_p| +.TE +. +.TP +.B otp_dump +Displays the content of the One Time Programmable (OTP) memory, which is part +of the SoC. These are 32 bit values, indexed from 8 to 64. See the +.BR raspi-otp (7) +for more details. +. +.TP +.BI get_mem \ type +Reports on the amount of memory allocated to the ARM cores with +.I vcgencmd get_mem arm +or the VC4 with +.IR "vcgencmd get_mem gpu" . +.IP +.B Note: +On a Raspberry Pi 4 with greater than 1GB of RAM, the +.I arm +option is inaccurate. +This is because the GPU firmware which implements this command is only aware of +the first gigabyte of RAM on the system, so the +.I arm +setting will always return +1GB minus the +.I gpu +memory value. To get an accurate report of the amount of ARM +memory, use one of the standard Linux commands, such as +.I free +or +.IR "cat /proc/meminfo" . +. +.TP +.BI codec_enabled \ type +Reports whether the specified CODEC type is enabled. Possible options for type +are AGIF, FLAC, H263, H264, MJPA, MJPB, MJPG, MPG2, MPG4, MVC0, PCM, THRA, +VORB, VP6, VP8, WMV9, WVC1. +.IP +MPG2, WMV9, and WVC1 currently require a paid for licence (see the +.B [FAQ] +for more info), except on the Pi4, where these hardware codecs are disabled in +preference to software decoding, which requires no licence. Note that because +the H265 hardware block on the Raspberry Pi4 is not part of the VideoCore GPU, +its status is not accessed via this command. +. +.TP +.BI get_config \ type|name +This returns all the configuration items of the specified type that have been +set in config.txt, or a single configuration item. Possible values for type +parameter are +.IR int ", " str ", " +or simply use the name of the configuration item. +. +.TP +.B get_lcd_info +Displays the resolution and colour depth of any attached display. +. +.TP +.B mem_oom +Displays statistics on any Out Of Memory events occuring in the VC4 memory +space. +. +.TP +.B mem_reloc_stats +Displays statistics from the relocatable memory allocator on the VC4. +. +.TP +.B read_ring_osc +Returns the curent speed voltage and temperature of the ring oscillator. +. +.TP +.B hdmi_timings +Displays the current HDMI settings timings. See +.B [VIDEO] +for details of the values returned. +. +.TP +.B dispmanx_list +Dump a list of all dispmanx items currently being displayed. +. +.TP +.BI display_power \ 0|1|-1 +.TQ +.BI display_power " 0|1|-1 display" +Show current display power state, or set the display power state. +.I vcgencmd display_power 0 +will turn off power to the current display. +.I vcgencmd display_power 1 +will turn on power to the display. If no parameter is set, this will display +the current power state. The final parameter is an optional display ID, as +returned by +.I tvservice -l +or from the table below, which allows a specific display to be turned on or +off. +.IP +.I vcgencmd display_power 0 7 +will turn off power to display ID 7, which is HDMI 1 on a Raspberry Pi 4. +.TS +tab(|); +l l . +Display|ID +\_|\_ +.T& +l n . +Main LCD|0 +Secondary LCD|1 +HDMI 0|2 +Composite|3 +HDMI 1|7 +.TE +.IP +To determine if a specific display ID is on or off, use -1 as the first +parameter. +.IP +.I vcgencmd display_power -1 7 +will return 0 if display ID 7 is off, 1 if display ID 7 is on, or -1 if display +ID 7 is in an unknown state, for example undetected. +. +. +.SH EXIT STATUS +. +.IP 0 +Command completed successfully +.IP -1 +Problem with VHCI +.IP -2 +VideoCore returned an error +. +. +.SH SEE ALSO +.B [SOURCE] +. +. +.SH REFERENCES +.TP +.B [BOOT] +https://www.raspberrypi.org/\:documentation/\:configuration/\:config-txt/\:boot.md +. +.TP +.B [FAQ] +https://www.raspberrypi.org/\:documentation/\:faqs/\:README.md +. +.TP +.B [SOURCE] +https://www.raspberrypi.org/\:documentation/\:raspbian/\:applications/\:vcgencmd.md +. +.TP +.B [VIDEO] +https://www.raspberrypi.org/\:documentation/\:configuration/\:config-txt/\:video.md diff --git a/host_applications/linux/apps/raspicam/CMakeLists.txt b/host_applications/linux/apps/raspicam/CMakeLists.txt index eb1ef7c89..e6bd37389 100644 --- a/host_applications/linux/apps/raspicam/CMakeLists.txt +++ b/host_applications/linux/apps/raspicam/CMakeLists.txt @@ -67,3 +67,5 @@ target_link_libraries(raspivid ${MMAL_LIBS} vcos bcm_host m) target_link_libraries(raspividyuv ${MMAL_LIBS} vcos bcm_host m) install(TARGETS raspistill raspiyuv raspivid raspividyuv RUNTIME DESTINATION bin) +install(FILES raspistill.1 raspiyuv.1 raspivid.1 raspividyuv.1 DESTINATION man/man1) +install(FILES raspicam.7 DESTINATION man/man7) diff --git a/host_applications/linux/apps/raspicam/raspicam.7 b/host_applications/linux/apps/raspicam/raspicam.7 new file mode 100644 index 000000000..dc8e3bf9d --- /dev/null +++ b/host_applications/linux/apps/raspicam/raspicam.7 @@ -0,0 +1,691 @@ +.TH RASPICAM 7 +. +.SH NAME +raspicam \- the Raspberry Pi Camera Module and its utilities +. +. +.SH DESCRIPTION +. +There are four applications provided: +.BR raspistill (1), +.BR raspivid (1), +.BR raspiyuv (1) +and +.BR raspividyuv (1). +.BR raspistill (1) +and +.BR raspiyuv (1) +are very similar and are intended for capturing images; +.BR raspivid (1) +and +.BR raspvidyuv (1) +are for recording video. +The utilities share many common options, which are documented in the sections +.BR "HARDWARE OPTIONS" , +.BR "PREVIEW OPTIONS" , +.BR "IMAGE OPTIONS" , +and +.BR "STEREOSCOPIC (3D) OPTIONS" +below. Within each section, options are listed alphabetically (by the +long-option's title). +.PP +All the applications are driven from the command line, and written to take +advantage of the MMAL API which runs over OpenMAX. The MMAL API provides an +easier to use system than that presented by OpenMAX. Note that MMAL is a +Broadcom-specific API used only on VideoCore 4 systems. +.PP +The applications use up to four OpenMAX (MMAL) components: camera, preview, +encoder, and null_sink. All applications use the camera component; +.BR raspistill (1) +uses the Image Encode component; +.BR raspivid (1) +uses the Video Encode component; and +.BR raspiyuv (1) +and +.BR raspividyuv (1) +don't use an encoder, sending their YUV or RGB output directly from the +camera component to file. +.PP +The preview display is optional, but can be used full-screen or directed to a +specific rectangular area on the display. If preview is disabled, the null_sink +component is used to 'absorb' the preview frames. The camera must produce +preview frames even if these aren't required for display, as they're used for +calculating exposure and white balance settings. +.PP +In addition, it's possible to omit the filename option (in which case the +preview is displayed but no file is written), or to redirect all output to +stdout. +. +. +.SH GETTING STARTED +. +.B Warning: +Cameras are sensitive to static. Earth yourself prior to handling the PCB. A +sink tap or similar should suffice if you don’t have an earthing strap. +.PP +The camera board attaches to the Raspberry Pi via a 15-way ribbon cable. There +are only two connections to make: the ribbon cable needs to be attached to the +camera PCB, and to the Raspberry Pi itself. You need to get the cable the right +way round, or the camera will not work. On the camera PCB, the blue backing on +the cable should face away from the PCB, and on the Raspberry Pi it should face +towards the Ethernet connection (or where the Ethernet connector would be if +you're using a model A+). +.PP +Although the connectors on the PCB and the Pi are different, they work in a +similar way. On the Raspberry Pi itself, pull up the tabs on each end of the +connector. It should slide up easily, and be able to pivot around slightly. +Fully insert the ribbon cable into the slot, ensuring it is set straight, then +gently press down the tabs to clip it into place. The camera PCB connector also +requires you to pull the tabs away from the board, gently insert the cable, +then push the tabs back. The PCB connector can be a little more awkward than +the one on the Pi itself. +. +. +.SH TROUBLESHOOTING +. +If the Camera Module isn't working correctly, there are number of things to +try: +.IP \(bu 2 +Is the ribbon cable attached to the Camera Serial Interface (CSI), not the +Display Serial Interface (DSI)? The ribbon connector will fit into either port. +The Camera port is located near the HDMI connector. +. +.IP \(bu +Are the ribbon connectors all firmly seated, and are they the right way round? +They must be straight in their sockets. +. +.IP \(bu +Is the Camera Module connector, between the smaller black Camera Module itself +and the PCB, firmly attached? Sometimes this connection can come loose during +transit or when putting the Camera Module in a case. Using a fingernail, flip +up the connector on the PCB, then reconnect it with gentle pressure. It engages +with a very slight click. Don't force it; if it doesn't engage, it's probably +slightly misaligned. +. +.IP \(bu +Have +.I sudo apt update +and +.I sudo apt full-upgrade +been run? +. +.IP \(bu +Is +.I start_x=1 +present in the \(lqconfig.txt\(rq boot configuration? +. +.IP \(bu +Is your power supply sufficient? The Camera Module adds about 200-250mA to the +power requirements of your Raspberry Pi. +. +.PP +Try the following in response to specific error messages: +. +.TP +.B Error : raspistill/raspivid command not found +This probably means your update/upgrade failed in some way. Try it again. +. +.TP +.B Error : ENOMEM +The Camera Module is not starting up. Check all connections again. +. +.TP +.B Error : ENOSPC +The Camera Module is probably running out of GPU memory. Check +\(lqconfig.txt\(rq on the boot partition. The +.I gpu_mem +option should be at least 128. +. +. +.SH HARDWARE OPTIONS +. +.TP +.BR \-cs ", " \-\-camselect " \fIcamera\fR" +Selects the camera to use on a multi-camera system (currently only Pi +Compute Modules). +Use 0 or 1. +. +.TP +.BR \-md ", " \-\-mode " \fImode\fR" +Sets a specified sensor mode, disabling the automatic selection. +Possible values depend on the version of the Camera Module being used: +.IP +Version 1.x (OV5647) +.TS +tab(|); +l l l l l l . +Mode|Size|Aspect|Framerates|FOV|Binning +\_|\_|\_|\_|\_|\_ +.T& +n c s s s s . +0|--- automatic selection --- +.T& +n l l l l l . +1|1920 x 1080|16:9|1 - 30fps|Partial|None +2|2592 x 1944|4:3|1 - 15fps|Full|None +3|2592 x 1944|4:3|0.1666 - 1fps|Full|None +4|1296 x 972|4:3|1 - 42fps|Full|2 x 2 +5|1296 x 730|16:9|1 - 49fps|Full|2 x 2 +6|640 x 480|4:3|42.1 - 60fps|Full|2 x 2 + skip +7|640 x 480|4:3|60.1 - 90fps|Full|2 x 2 + skip +.TE +.IP +Version 2.x (IMX219) +.TS +tab(|); +l l l l l l . +Mode|Size|Aspect|Framerates|FOV|Binning +\_|\_|\_|\_|\_|\_ +.T& +n c s s s s . +0|--- automatic selection --- +.T& +n l l l l l . +1|1920 x 1080|16:9|0.1 - 30fps|Partial|None +2|3280 x 2464|4:3|0.1 - 15fps|Full|None +3|3280 x 2464|4:3|0.1 - 15fps|Full|None +4|1640 x 1232|4:3|0.1 - 40fps|Full|2 x 2 +5|1640 x 922|16:9|0.1 - 40fps|Full|2 x 2 +6|1280 x 720|16:9|40 - 90fps|Partial|2 x 2 +7|640 x 480|4:3|40 - 200fps*|Partial|2 x 2 +.TE +.IP +* For frame rates over 120fps, it is necessary to turn off automatic exposure +and gain control using +.IR "-ex off" . +Doing so should achieve the higher frame rates, but exposure time and gains +will need to be set to fixed values supplied by the user. +.IP +HQ Camera (IMX477) +.TS +tab(|); +l l l l l l . +Mode|Size|Aspect|Framerates|FOV|Binning +\_|\_|\_|\_|\_|\_ +.T& +n c s s s s . +0|--- automatic selection --- +.T& +n l l l l l . +1|2028 x 1080|169:90|0.1 - 50fps|Partial|2 x 2 +2|2028 x 1520|4:3|0.1 - 50fps|Full|2 x 2 +3|4056 x 3040|4:3|0.005 - 10fps|Full|None +4|1012 x 760|4:3|50.1 - 120fps|Full|4 x 4 +.TE +. +.TP +.BR \-gps ", " \-\-gpsdexif +Applies real-time EXIF information from any attached GPS dongle (using GSPD) to +the image; requires +.I libgps.so +to be installed. +. +. +.SH PREVIEW OPTIONS +. +.TP +.BR \-dn ", " \-\-dispnum " \fIscreen\fR" +Specifies which display the camera preview should appear on, using dispmanx / +tvservice numbering (see the output of +.I tvservice -l +or the +.I display_power +command under +.BR vcgencmd (1) +for more information). +. +.TP +.BR \-f ", " \-\-fullscreen +Forces the preview window to use the whole screen. Note that the aspect ratio +of the incoming image will be retained, so there may be bars on some edges. +. +.TP +.BR \-n ", " \-\-nopreview +Disables the preview window completely. Note that even though the preview is +disabled, the camera will still be producing frames, so will be using power. +. +.TP +.BR \-op ", " \-\-opacity " \fIvalue\fR" +Sets the opacity of the preview window. 0 = invisible, 255 = fully opaque. +. +.TP +.BR \-p ", " \-\-preview " \fIx,y,w,h\fR" +Allows the user to define the size of the preview window and its location on +the screen. Note this will be superimposed over the top of any other +windows/graphics. +. +. +.SH IMAGE OPTIONS +. +.TP +.BR \-a ", " \-\-annotate " \fIflags|text\fR" +Adds some text and/or metadata to the picture. +.IP +Metadata is indicated using a bitmask notation, so add them together to show +multiple parameters. For example, 12 will show time (4) and date (8), since +4+8=12. +.IP +Text may include date/time placeholders by using the '%' character, as used by +.BR strftime (3). +.RS +.TP +.B \-a 4 +Displays the time, "20:09:33" +.TP +.B \-a 8 +Displays the date, "10/28/15" +.TP +.B \-a 16 +Shutter settings +.TP +.B \-a 32 +CAF settings +.TP +.B \-a 64 +Gain settings +.TP +.B \-a 128 +Lens settings +.TP +.B \-a 256 +Motion settings +.TP +.B \-a 512 +Frame number +.TP +.B \-a 1024 +Black background +.TP +.B \-a "ABC" +Show the specified text, "ABC" +.TP +.B \-a "ABC %Y\-%m\-%d" +Show the specified text, "ABC %Y\-%m\-%d" +.TP +.B \-a 4 \-a "ABC %Y\-%m\-%d %X" +Displays a formatted timestamp, "ABC 2015\-10\-28 20:09:33" +.TP +.B \-a 8 \-a "ABC %Y\-%m\-%d %X" +Also displays a formatted timestamp, "ABC 2015\-10\-28 20:09:33" +.RE +. +.TP +.BR \-ae ", " \-\-annotateex " \fIsize,fg,bg\fR" +Specifies annotation size, text color, and background color. Colors are in +hex YUV format. +Size ranges from 6 - 160; default is 32. Asking for an invalid size should give +you the default. +.IP +For example, to obtain size 32 white text on a black background: +.IP +.EX +-ae 32,0xff,0x808000 -a "Annotation text" +.EE +.IP +Or for size 10 black text on a white background: +.IP +.EX +-ae 10,0x00,0x8080FF -a "Annotation text" +.EE +. +.TP +.BR \-ag ", " \-\-analoggain " \fIvalue\fR" +Sets the analog gain value directly on the sensor (floating point value from +1.0 to 8.0 for the OV5647 sensor on V1 Camera Module, and 1.0 to 12.0 for the +IMX219 sensor on V1 Camera Module and the IMX447 on the HQ Camera). +. +.TP +.BR \-awb ", " \-\-awb " \fImode\fR" +Modes for which color temperature ranges (in Kelvin) are available have these +settings in brackets. +.RS +.TP +.B off +turn off white balance calculation +.TP +.B auto +automatic mode (default) +.TP +.B sun +sunny mode (between 5000K and 6500K) +.TP +.B cloud +cloudy mode (between 6500K and 12000K) +.TP +.B shade +shade mode +.TP +.B tungsten +tungsten lighting mode (between 2500K and 3500K) +.TP +.B fluorescent +fluorescent lighting mode (between 2500K and 4500K) +.TP +.B incandescent +incandescent lighting mode +.TP +.B flash +flash mode +.TP +.B horizon +horizon mode +.TP +.B greyworld +used on the NoIR camera to fix incorrect AWB results due to the lack of the IR +filter +.RE +.IP +Note that not all of these settings may be implemented, depending on camera +type. +. +.TP +.BR \-awbg ", " \-\-awbgains " \fIblue,red\fR" +Sets blue and red gains (as floating point numbers) to be applied when +.I \-awb off +is set e.g. +.I \-awbg 1.5,1.2 +. +.TP +.BR \-br ", " \-\-brightness " \fIvalue\fR" +Sets the brightness of the image, from 0 to 100. 50 is the default. +. +.TP +.BR \-cfx ", " \-\-colfx " \fIu:v\fR" +The supplied U and V parameters (range 0 - 255) are applied to the U and Y +channels of the image. For example, +.I \-\-colfx 128:128 +should result in a monochrome image. +. +.TP +.BR \-co ", " \-\-contrast " \fIvalue\fR" +Sets the contrast of the image, from -100 to 100. 0 is the default. +. +.TP +.BR \-dg ", " \-\-digitalgain " \fIvalue\fR" +Sets the digital gain value applied by the ISP (floating point value from 1.0 +to 64.0, but values over about 4.0 will produce overexposed images). +. +.TP +.BR \-drc ", " \-\-drc " \fIvalue\fR" +Dynamic range control (DRC) changes the images by increasing the range of dark +areas, and decreasing the brighter areas. This can improve the image in low +light areas. Valid values are +.IR off " (default), " low ", " med ", or " high. +. +.TP +.BR \-ev ", " \-\-ev " \fIvalue\fR" +Sets the exposure value compensation, from -10 to 10. 0 is the default. +. +.TP +.BR \-ex ", " \-\-exposure " \fImode\fR" +Sets the exposure mode of the camera. Possible options are: +.RS +.TP +.B auto +use automatic exposure mode (default) +.TP +.B night +select setting for night shooting +.TP +.B nightpreview + +.TP +.B backlight +select setting for backlit subject +.TP +.B spotlight + +.TP +.B sports +select setting for sports (fast shutter etc.) +.TP +.B snow +select setting optimized for snowy scenery +.TP +.B beach +select setting optimized for beach +.TP +.B verylong +select setting for long exposures +.TP +.B fixedfps +constrain fps to a fixed value +.TP +.B antishake +select "antishake" mode +.TP +.B fireworks +select setting optimized for fireworks +.RE +.IP +Note that not all of these settings may be implemented, depending on camera +tuning. +. +.TP +.BR \-fli ", " \-\-flicker " \fImode\fR" +Set a mode to compensate for lights flickering at the mains frequency, which +can be seen as a dark horizontal band across an image. Flicker avoidance locks +the exposure time to a multiple of the mains flicker frequency (8.33ms for +60Hz, or 10ms for 50Hz). This means that images can be noisier as the control +algorithm has to increase the gain instead of exposure time should it wish for +an intermediate exposure value. +.I auto +can be confused by external factors, therefore it is preferable to leave this +setting off unless actually required. +.IP +Possible options are: +.RS +.TP +.B off +turn off flicker avoidance +.TP +.B auto +automatically detect mains frequency +.TP +.B 50hz +set avoidance at 50Hz +.TP +.B 60hz +set avoidance at 60Hz +.RE +. +.TP +.BR \-hf ", " \-\-hflip +Flips the preview and saved image horizontally. +. +.TP +.BR \-ifx ", " \-\-imxfx " \fIeffect\fR" +Set an effect to be applied to the image: +.RS +.TP +.B none +no effect (default) +.TP +.B negative +invert the image colors +.TP +.B solarise +solarize the image +.TP +.B posterise +posterize the image +.TP +.B whiteboard +whiteboard effect +.TP +.B blackboard +blackboard effect +.TP +.B sketch +sketch effect +.TP +.B denoise +denoise the image +.TP +.B emboss +emboss the image +.TP +.B oilpaint +oil paint effect +.TP +.B hatch +hatch sketch effect +.TP +.B gpen +graphite sketch effect +.TP +.B pastel +pastel effect +.TP +.B watercolour +watercolor effect +.TP +.B film +film grain effect +.TP +.B blur +blur the image +.TP +.B saturation +saturate the image color +.TP +.B colourswap +not fully implemented +.TP +.B washedout +not fully implemented +.TP +.B colourpoint +not fully implemented +.TP +.B colourbalance +not fully implemented +.TP +.B cartoon +not fully implemented +.RE +.IP +Note that not all of these settings may be available in all circumstances. +. +.TP +.BR \-ISO ", " \-\-ISO " \fIvalue\fR" +Sets the ISO to be used for captures, from 100 to 800. The default is +automatic. +. +.TP +.BR \-mm ", " \-\-metering " \fImode\fR" +Specify the metering mode used for the preview and capture: +.RS +.TP +.B average +average the whole frame for metering +.TP +.B spot +spot metering in the center of the frame +.TP +.B backlit +assume a backlit image +.TP +.B matrix +matrix metering +.RE +. +.TP +.BR \-roi ", " \-\-roi " \fIx,y,w,h\fR" +Allows the specification of the area of the sensor to be used as the source for +the preview and capture. This is defined as x,y for the top-left corner, and a +width and height, with all values in normalised coordinates (0.0 - 1.0). So, to +set a ROI at halfway across and down the sensor, and a width and height of a +quarter of the sensor, use: +.IP +.EX +-roi 0.5,0.5,0.25,0.25 +.EE +. +.TP +.BR \-rot ", " \-\-rotation " \fIvalue\fR" +Sets the rotation of the image in the viewfinder and resulting image. This can +take any value from 0 upwards, but due to hardware constraints only 0, 90, 180, +and 270 degree rotations are supported. +. +.TP +.BR \-sa ", " \-\-saturation " \fIvalue\fR" +Sets the color saturation of the image, from -100 to 100. 0 is the default. +. +.TP +.BR \-set ", " \-\-settings +Retrieves the current camera settings and writes them to stdout. +. +.TP +.BR \-sh ", " \-\-sharpness " \fIvalue\fR" +Sets the sharpness of the image, from -100 to 100. 0 is the default. +. +.TP +.BR \-ss ", " \-\-shutter " \fIvalue\fR" +Sets the shutter open time to the specified value (in microseconds). Shutter +speed limits are as follows: +.TS +tab(|); +l l . +Camera Model|Max (microseconds) +\_|\_ +.T& +l n . +Version 1.x (OV5647)|6000000\& (6s) +Version 2.x (IMX219)|10000000\& (10s) +HQ (IMX477)|200000000\& (200s) +.TE +.IP +Using values above these maximums will result in undefined behaviour. +. +.TP +.BR \-st ", " \-\-stats +Force recomputation of statistics on stills capture pass. Digital gain and AWB +are recomputed based on the actual capture frame statistics, rather than the +preceding preview frame. +. +.TP +.BR \-vf ", " \-\-vflip +Flips the preview and saved image horizontally. +. +.TP +.BR \-vs ", " \-\-vstab +In video mode only, turns on video stabilisation. +. +. +.SH STEREOSCOPIC (3D) OPTIONS +. +.TP +.BR \-3dswap ", " \-\-3dswap +Swaps the camera order used in stereoscopic imaging; +.B NOTE: +currently not working. +. +.TP +.BR \-dec ", " \-\-decimate +Halves the width and height of the stereo image. +. +.TP +.BR \-3d ", " \-\-stereo " \fImode\fR" +Select the specified stereo imaging mode; +.I sbs +selects side-by-side mode, +.I tb +selects top/bottom mode; +.I off +turns off stereo mode (the default). +. +. +.SH SEE ALSO +.BR raspistill (1), +.BR raspiyuv (1), +.BR raspivid (1), +.BR raspividyuv (1), +.BR vcgencmd (1), +.B [SOURCE] +. +. +.SH REFERENCES +.TP +.B [SOURCE] +https://www.raspberrypi.org/\:documentation/\:raspbian/\:applications/\:camera.md diff --git a/host_applications/linux/apps/raspicam/raspistill.1 b/host_applications/linux/apps/raspicam/raspistill.1 new file mode 100644 index 000000000..8d8a5e282 --- /dev/null +++ b/host_applications/linux/apps/raspicam/raspistill.1 @@ -0,0 +1,461 @@ +.TH RASPISTILL 1 +. +.SH NAME +raspistill \- takes still JPEG captures with the Pi Camera Module +. +. +.SH SYNOPSIS +.SY raspistill +.OP \-3d mode +.OP \-3dswap +.OP \-a flags|text +.OP \-ae size,fg,bg +.OP \-ag value +.OP \-awb mode +.OP \-awbg b,r +.OP \-bm +.OP \-br value +.OP \-cfx u:v +.OP \-co value +.OP \-cs camera +.OP \-d ms +.OP \-dec +.OP \-dg value +.OP \-dn screen +.OP \-drc value +.OP \-dt +.OP \-e format +.OP \-ev value +.OP \-ex mode +.OP \-f +.OP \-fli mode +.OP \-fp +.OP \-fs num +.OP \-g +.OP \-gc +.OP \-gps +.OP \-gs scene +.OP \-gw x,y,w,h +.OP \-h size +.OP \-hf +.OP \-ifx effect +.OP \-ISO value +.OP \-k +.OP \-l filename +.OP \-md mode +.OP \-mm mode +.OP \-n +.OP \-o filename +.OP \-op opacity +.OP \-p x,y,w,h +.OP \-q quality +.OP \-r +.OP \-roi x,y,w,h +.OP \-rot value +.OP \-rs num +.OP \-s +.OP \-sa value +.OP \-set +.OP \-sh value +.OP \-ss value +.OP \-st +.OP \-t ms +.OP \-th x:y:q +.OP \-tl ms +.OP \-ts +.OP \-v +.OP \-vf +.OP \-w size +.OP \-x key=value +.YS +. +.SY raspistill +.OP \-? +.SY raspistill +.OP \-\-help +.YS +. +. +.SH DESCRIPTION +.B raspistill +is a command line utility for capturing still images from the Raspberry Pi +Camera Module (any version). It has numerous options which can be used to +customize the capture process, the preview display, or to perform more complex +operations like time-lapse or triggered captures. +. +. +.SH OPTIONS +The options documented in the following sections are specific to the +.B raspistill +utility, or commonly used with it. For full details of the other options (which +are common to all the camera utilities), please refer to the +.BR raspicam (7) +manual page. +. +. +.SH GENERAL OPTIONS +. +.TP +.BR \-? ", " \-\-help +Display a concise description of all parameters +. +.TP +.BR \-bm ", " \-\-burst +Sets burst capture mode. This prevents the camera from returning to preview +mode in between captures, meaning that captures can be taken closer together. +. +.TP +.BR \-d ", " \-\-demo " [\fIms\fR]" +This options cycles through the range of camera options. No capture is taken, +and the demo will end at the end of the timeout period, irrespective of whether +all the options have been cycled. The time between cycles should be specified +as a millisecond value. +. +.TP +.BR \-e ", " \-\-encoding " \fIformat\fR" +Valid options are +.IR jpg " (default)," +.IR bmp , +.IR gif ", and" +.IR png . +Note that only the JPEG format +.RI ( "-e jpg" ) +is hardware accelerated. All other image types will take much longer to save. +Also note that the filename suffix is completely ignored when deciding the +encoding of a file. +. +.TP +.BR \-x ", " \-\-exif " \fIkey=value\fR" +Allows the insertion of specific EXIF tags into the JPEG image. You can have up +to 32 EXIF tag entries. This is useful for tasks like adding GPS metadata. For +example, to set the longitude: +.IP +.EX +--exif GPS.GPSLongitude=5/1,10/1,15/1 +.EE +.IP +would set the longitude to 5 degs, 10 minutes, 15 seconds. See +.B [EXIF] +documentation for more details on the range of tags available; the supported +tags are as follows: +.RS +.TP +.B IFD0. +.TQ +.B IFD1. +ImageWidth, ImageLength, BitsPerSample, Compression, PhotometricInterpretation, +ImageDescription, Make, Model, StripOffsets, Orientation, SamplesPerPixel, +RowsPerString, StripByteCounts, XResolution, YResolution, PlanarConfiguration, +ResolutionUnit, TransferFunction, Software, DateTime, Artist, WhitePoint, +PrimaryChromaticities, JPEGInterchangeFormat, JPEGInterchangeFormatLength, +YCbCrCoefficients, YCbCrSubSampling, YCbCrPositioning, ReferenceBlackWhite, +Copyright +.TP +.B EXIF. +ExposureTime, FNumber, ExposureProgram, SpectralSensitivity, ISOSpeedRatings, +OECF, ExifVersion, DateTimeOriginal, DateTimeDigitized, +ComponentsConfiguration, CompressedBitsPerPixel, ShutterSpeedValue, +ApertureValue, BrightnessValue, ExposureBiasValue, MaxApertureValue, +SubjectDistance, MeteringMode, LightSource, Flash, FocalLength, SubjectArea, +MakerNote, UserComment, SubSecTime, SubSecTimeOriginal, SubSecTimeDigitized, +FlashpixVersion, ColorSpace, PixelXDimension, PixelYDimension, +RelatedSoundFile, FlashEnergy, SpatialFrequencyResponse, FocalPlaneXResolution, +FocalPlaneYResolution, FocalPlaneResolutionUnit, SubjectLocation, +ExposureIndex, SensingMethod, FileSource, SceneType, CFAPattern, +CustomRendered, ExposureMode, WhiteBalance, DigitalZoomRatio, +FocalLengthIn35mmFilm, SceneCaptureType, GainControl, Contrast, Saturation, +Sharpness, DeviceSettingDescription, SubjectDistanceRange, ImageUniqueID +.TP +.B GPS. +GPSVersionID, GPSLatitudeRef, GPSLatitude, GPSLongitudeRef, GPSLongitude, +GPSAltitudeRef, GPSAltitude, GPSTimeStamp, GPSSatellites, GPSStatus, +GPSMeasureMode, GPSDOP, GPSSpeedRef, GPSSpeed, GPSTrackRef, GPSTrack, +GPSImgDirectionRef, GPSImgDirection, GPSMapDatum, GPSDestLatitudeRef, +GPSDestLatitude, GPSDestLongitudeRef, GPSDestLongitude, GPSDestBearingRef, +GPSDestBearing, GPSDestDistanceRef, GPSDestDistance, GPSProcessingMethod, +GPSAreaInformation, GPSDateStamp, GPSDifferential +.TP +.B EINT. +InteroperabilityIndex, InteroperabilityVersion, RelatedImageFileFormat, +RelatedImageWidth, RelatedImageLength +.RE +. +.TP +.BR \-fp ", " \-\-fullpreview +This runs the preview using the full resolution capture mode. Maximum frames +per second in this mode is 15fps, and the preview will have the same field of +view as the capture. Captures should happen more quickly, as no mode change +should be required. This feature is currently under development. +. +.TP +.BR \-h ", " \-\-height " \fIsize\fR" +Set the image height to +.IR size . +. +.TP +.BR \-k ", " \-\-keypress +The camera is run for the requested time +.RI ( \-t ), +and a capture can be initiated throughout that time by pressing the Enter key. +Pressing X then Enter will exit the application before the timeout is reached. +If the timeout is set to 0, the camera will run indefinitely until the user +presses X then Enter. Using the verbose option +.RI ( \-v ) +will display a prompt asking for user input, otherwise no prompt is displayed. +. +.TP +.BR \-l ", " \-\-latest " \fIfilename\fR" +Makes a file system link under this name to the latest frame. +. +.TP +.BR \-o ", " \-\-output " \fIfilename\fR" +Specifies the output filename. If not specified, no file is saved. +If the filename is \(lq\-\(rq, then all output is send to stdout. +. +.TP +.BR \-q ", " \-\-quality " \fIvalue\fR" +Sets the JPEG compression quality from 0 to 100. 100 is nearly uncompressed, 75 +is a good all-round value. +. +.TP +.BR \-r ", " \-\-raw +This option inserts the raw Bayer data from the camera into the JPEG metadata. +. +.TP +.BR \-rs ", " \-\-restart " \fInum\fR" +Sets the JPEG restart marker interval to a specific value. Can be useful for +lossy transport streams because it allows a broken JPEG file to still be +partially displayed. +. +.TP +.BR \-s ", " \-\-signal +The camera is run for the requested time +.RI ( -t ), +and a capture can be initiated throughout that time by sending a USR1 signal to +the camera process. This can be done using the +.BR killall (1) +command. For example: +.IP +.EX +killall -USR1 raspistill +.EE +. +.TP +.BR \-th ", " \-\-thumb " \fIx:y:q\fR" +Allows specification of the thumbnail image inserted into the JPEG file. If not +specified, defaults are a size of 64x48 at quality 35. +. +If +.I \-\-thumb none +is specified, no thumbnail information will be placed in the file. This reduces +the file size slightly. +. +.TP +.BR \-t ", " \-\-timeout " \fIms\fR" +The program will run for the specified length of time, in milliseconds. +It then takes the capture and saves it if an output is specified. If a timeout +value is not specified, then it is set to 5 seconds +.RI ( "\-t 5000" ). +Note that low values (less than 500ms, although it can depend on other +settings) may not give enough time for the camera to start up and provide +enough frames for the automatic algorithms like AWB and AGC to provide accurate +results. +. +If set to 0, the preview will run indefinitely, until stopped with Ctrl-C. In +this case no capture is made. +. +.TP +.BR \-v ", " \-\-verbose +Outputs debugging/information messages during the program run. +. +.TP +.BR \-w ", " \-\-width " \fIsize\fR" +Set the image width to +.IR size . +. +. +.SH TIMELAPSE OPTIONS +. +.TP +.BR \-tl ", " \-\-timelapse " \fIms\fR" +The specific value is the time between shots in milliseconds. Note that you +should specify +.I %04d +at the point in the filename where you want a frame count number to appear. So, +for example, the code below will produce a capture every 2 seconds, over a +total period of 30s, named \(lqimage0001.jpg\(rq, \(lqimage0002.jpg\(rq and so +on, through to \(lqimage0015.jpg\(rq: +.IP +.EX +-t 30000 -tl 2000 -o image%04d.jpg +.EE +.IP +Note that the +.I %04d +indicates a 4-digit number, with leading zeroes added to make the required +number of digits. So, for example, +.I %08d +would result in an 8-digit number. +. +If a timelapse value of 0 is entered, the application will take pictures as +fast as possible. Note that there's an minimum enforced pause of 30ms between +captures to ensure that exposure calculations can be made. +. +.TP +.BR \-dt ", " \-\-datetime +Instead of a simple frame number, the timelapse +.RI ( \-tl ) +filenames will use a date/time value of the format mmddHHMMSS, where mm is the +month, dd is the day of the month, HH is the hour, MM is the minute, and SS is +the second. +. +.TP +.BR \-fr ", " \-\-framestart " \fInum\fR" +Specifies the first frame number in the timelapse +.RI ( \-tl ). +Useful if you have already saved a number of frames, and want to start again at +the next frame. +. +.TP +.BR \-ts ", " \-\-timestamp +Instead of a simple frame number, the timelapse +.RI ( \-tl ) +file names will use a single number which is the Unix timestamp, i.e. the +seconds since 1970. +. +. +.SH GL OPTIONS +. +.TP +.BR \-g ", " \-\-gl +Draw preview to texture instead of using video render component. +. +.TP +.BR \-gc ", " \-\-glcapture +Capture the GL frame-buffer instead of the camera image. +. +.TP +.BR \-gs ", " \-\-glscene " \fIscene\fR" +Select the GL scene which can be +.IR square , +.IR teapot , +.IR mirror , +.IR yuv , +.IR sobel ", or" +.IR vcsm_square . +. +.TP +.BR \-gw ", " \-\-glwin " \fIx,y,w,h\fR" +Specifies the GL window settings as an +.I x,y +location and a width and height. +. +. +.SH EXIT STATUS +. +.IP 0 +Application ran successfully +.RB ( EX_OK ) +.IP 64 +Bad command line parameter +.RB ( EX_USAGE ) +.IP 70 +Software or camera error +.RB ( EX_SOFTWARE ) +.IP 130 +Application terminated by Ctrl-C +. +. +.SH EXAMPLES +. +By default, captures are done at the highest resolution supported by the +sensor. This can be changed using the +.I \-w +and +.I \-h +command line options. +. +.TP +.B raspistill \-t 2000 \-o image.jpg +Take a default capture after 2s (times are specified in milliseconds) on the +viewfinder, saving in image.jpg. +. +.TP +.B raspistill \-t 2000 \-o image.jpg \-w 640 \-h 480 +Take a capture at a different resolution. +. +.TP +.B raspistill \-t 2000 \-o image.jpg \-q 5 +Reduce the quality considerably to reduce file size. +. +.TP +.B raspistill \-t 2000 \-o image.jpg \-p 100,100,300,200 +Force the preview to appear at coordinate 100,100, with width 300 pixels and +height 200 pixels. +. +.TP +.B raspistill \-t 2000 \-o image.jpg \-n +Disable the preview entirely. +. +.TP +.B raspistill \-t 2000 \-o image.png –e png +Save the image as a PNG file (lossless compression, but slower than JPEG). Note +that the filename suffix is ignored when choosing the image encoding. +. +.TP +.B raspistill \-t 2000 \-o image.jpg \-x IFD0.Artist=Boris \-x GPS.GPSAltitude=1235/10 +Add some EXIF information to the JPEG. This sets the Artist tag name to Boris, +and the GPS altitude to 123.5m. Note that if setting GPS tags you should set as +a minimum GPSLatitude, GPSLatitudeRef, GPSLongitude, GPSLongitudeRef, +GPSAltitude, and GPSAltitudeRef. +. +.TP +.B raspistill \-t 2000 \-o image.jpg \-ifx emboss +Set an emboss image effect. +. +.TP +.B raspistill \-t 2000 \-o image.jpg \-cfx 128:128 +Set the U and V channels of the YUV image to specific values (128:128 produces +a greyscale image). +. +.TP +.B raspistill \-t 2000 +Run preview for 2s, with no saved image. +. +.TP +.B raspistill \-t 600000 \-tl 10000 \-o image_num_%03d_today.jpg \-l latest.jpg +Take a time-lapse picture, every 10 seconds for 10 minutes (10 minutes = +600000ms), naming the files \(lqimage_num_001_today.jpg\(rq, +\(lqimage_num_002_today.jpg\(rq and so on, with the latest picture also +available under the name \(lqlatest.jpg\(rq. +. +.TP +.B raspistill \-t 2000 \-o \- +Take a picture and send the image data to stdout. +. +.TP +.B raspistill \-t 2000 \-o \- > my_file.jpg +Take a picture and send the image data to a file. +. +.TP +.B raspistill \-t 0 \-k \-o my_pics%02d.jpg +Run the camera forever, taking a picture when Enter is pressed. +. +. +.SH SEE ALSO +.BR raspicam (7), +.BR raspivid (1), +.BR raspividyuv (1), +.BR raspiyuv (1), +.BR vcgencmd (1), +.B [SOURCE] +. +. +.SH REFERENCES +.TP +.B [EXIF] +https://en.wikipedia.org/wiki/Exif +. +.TP +.B [SOURCE] +https://www.raspberrypi.org/\:documentation/\:raspbian/\:applications/\:camera.md diff --git a/host_applications/linux/apps/raspicam/raspivid.1 b/host_applications/linux/apps/raspicam/raspivid.1 new file mode 100644 index 000000000..3a1d203f1 --- /dev/null +++ b/host_applications/linux/apps/raspicam/raspivid.1 @@ -0,0 +1,482 @@ +.TH RASPIVID 1 +. +.SH NAME +raspivid \- records H264 video with the Pi Camera Module +. +. +.SH SYNOPSIS +.SY raspivid +.OP \-3d mode +.OP \-3dswap +.OP \-ISO value +.OP \-a flags|text +.OP \-ae size,fg,bg +.OP \-ag value +.OP \-awb mode +.OP \-awbg b,r +.OP \-b bps +.OP \-br value +.OP \-c +.OP \-cd name +.OP \-cfx u:v +.OP \-co value +.OP \-cs camera +.OP \-d ms +.OP \-dg value +.OP \-dn screen +.OP \-drc value +.OP \-e +.OP \-ev value +.OP \-ex mode +.OP \-f +.OP \-fl +.OP \-fli mode +.OP \-fps fps +.OP \-g frames +.OP \-gps +.OP \-h size +.OP \-hf +.OP \-i state +.OP \-if type +.OP \-ifx effect +.OP \-ih +.OP \-k +.OP \-l +.OP \-lev level +.OP \-md mode +.OP \-mm mode +.OP \-n +.OP \-o filename +.OP \-op opacity +.OP \-p x,y,w,h +.OP \-pf profile +.OP \-pts filename +.OP \-qp num +.OP \-r filename +.OP \-rf format +.OP \-roi x,y,w,h +.OP \-rot value +.OP \-s +.OP \-sa value +.OP \-set +.OP \-sg ms +.OP \-sh value +.OP \-sl num +.OP \-sn num +.OP \-sp +.OP \-ss value +.OP \-stm +.OP \-t ms +.OP \-td on,off +.OP \-v +.OP \-vf +.OP \-w size +.OP \-wr num +.OP \-x filename +.YS +. +.SY raspivid +.OP \-? +.SY raspivid +.OP \-\-help +.YS +. +. +.SH DESCRIPTION +.B raspivid +is a command line utility for recording video from the Raspberry Pi Camera +Module (any version). It has numerous options which can be used to customize +the recording, the preview display, or to perform more complex operations like +circular buffering and video streaming. +. +. +.SH OPTIONS +The options documented in the following sections are specific to the +.B raspivid +utility, or commonly used with it. For full details of the other options (which +are common to all the camera utilities), please refer to the +.BR raspicam (7) +manual page. +. +. +.SH GENERAL OPTIONS +. +.TP +.BR \-? ", " \-\-help +Display a concise description of all parameters +. +.TP +.BR \-b ", " \-\-bitrate " \fIbps\fR" +Use bits per second, so 10Mbits/s would be +.IR "\-b 10000000" . +For H264, 1080p30 a high quality bitrate would be 15Mbits/s or more. +Maximum bitrate is 25Mbits/s +.RI ( "\-b 25000000" ), +but much over 17Mbits/s won't show noticeable improvement at 1080p30. +. +.TP +.BR \-c ", " \-\-circular +Select circular buffer mode. All encoded data is stored in a circular buffer +until a trigger is activated, then the buffer is saved. +. +.TP +.BR \-cd ", " \-\-codec " \fIname\fR" +Specifies the encoder codec to use. Options are +.I H264 +and +.IR MJPEG . +H264 can encode up to 1080p, whereas MJPEG can encode upto the sensor size, but +at decreased framerates due to the higher processing and storage requirements. +. +.TP +.BR \-d ", " \-\-demo " [\fIms\fR]" +This options cycles through the range of camera options. No recording is taken, +and the demo will end at the end of the timeout period, irrespective of whether +all the options have been cycled. The time between cycles should be specified +as a millisecond value. +. +.TP +.BR \-fl ", " \-\-flush +Forces a flush of output data buffers as soon as video data is written. This +bypasses any OS caching of written data, and can decrease latency. +. +.TP +.BR \-fps ", " \-\-framerate " \fIfps\fR" +Specifies the frames per second to record. At present, the minimum frame rate +allowed is 2fps, and the maximum is 30fps. This is likely to change in the +future. +. +.TP +.BR \-h ", " \-\-height " \fIsize\fR" +Set the video height to +.IR size . +. +.TP +.BR \-if ", " \-\-irefresh " \fItype\fR" +Sets the H264 intra-refresh type. Possible types are: +.RS +.IP \(bu 2 +.I cyclic +.IP \(bu +.I adaptive +.IP \(bu +.I both +.IP \(bu +.I cyclicrows +.RE +. +.TP +.BR \-i ", " \-\-initial " \fIstate\fR" +Define whether the camera will start paused or will immediately start +recording. Valid states are +.I record +or +.IR pause . +Note that if you are using a simple timeout (without +.I \-\-timed +or +.I \-\-keypress +or other options to activate recording), and +.I \-\-initial +is set to +.IR pause , +no output will be recorded. +. +.TP +.BR \-ih ", " \-\-inline +Forces the stream to include PPS and SPS headers on every I-frame. Needed for +certain streaming cases e.g. Apple HLS. These headers are small, so don't +greatly increase the file size. +. +.TP +.BR \-g ", " \-\-intra " \fIframes\fR" +Sets the intra refresh period (GoP) rate for the recorded video. H264 video +uses a complete frame (I-frame) every intra refresh period, from which +subsequent frames are based. This option specifies the number of frames between +each I-frame. Larger numbers here will reduce the size of the resulting video, +and smaller numbers make the stream less error-prone. +. +.TP +.BR \-k ", " \-\-keypress +On each press of the Enter key, the recording will be paused or restarted. +Pressing X then Enter will stop recording and close the application. Note that +the timeout value +.RI ( \-t ) +will be used to signal the end of recording, but is only checked after each +Enter keypress; so if the system is waiting for a keypress, even if the timeout +has expired, it will still wait for the keypress before exiting. +. +.TP +.BR \-lev ", " \-\-level " \fIlevel\fR" +Specifies the H264 encoder level to use for encoding. Options are +.IR 4 , +.IR 4.1 , +and +.IR 4.2 . +. +.TP +.BR \-l ", " \-\-listen +When using a network connection as the +.IR \-\-output , +this option will make the sytem wait for a connection from the remote system +before sending data. +. +.TP +.BR \-o ", " \-\-output " \fIfilename\fR" +Specify the output filename. If not specified, no file is saved. If the +filename is \(lq\-\(rq, then all output is sent to stdout. +. +To connect to a remote IPv4 host, use +.I tcp +or +.I udp +followed by the required IP Address. e.g. +.I tcp://192.168.1.2:1234 +or +.IR udp://192.168.1.2:1234 . +.IP +To listen on a TCP port (IPv4) and wait for an incoming connection use the +.I \-\-listen +option, e.g. +.I raspivid \-l \-o tcp://0.0.0.0:3333 +will bind to all network interfaces, +.I raspivid \-l \-o tcp://192.168.1.1:3333 +will bind to a local IPv4. +. +.TP +.BR \-e ", " \-\-penc +Switch on this option to display the preview after compression. This will show +any compression artefacts in the preview window. In normal operation, the +preview will show the camera output prior to being compressed. This option is +not guaranteed to work in future releases. +. +.TP +.BR \-pf ", " \-\-profile " \fIprofile\fR" +Sets the H264 profile to be used for the encoding. Options are: +.RS +.IP \(bu 2 +.I baseline +.IP \(bu +.I main +.IP \(bu +.I high +.RE +. +.TP +.BR \-qp ", " \-\-qp " \fInum\fR" +Sets the initial quantisation parameter for the stream. Varies from +approximately 10 to 40, and will greatly affect the quality of the recording. +Higher values reduce quality and decrease file size. Combine this setting with +a bitrate of 0 to set a completely variable bitrate. +. +.TP +.BR \-r ", " \-\-raw " \fIfilename\fR" +Specify the output file name for any raw data files requested. +. +.TP +.BR \-rf " ," \-\-raw\-format " \fIformat\fR" +Specify the raw format to be used if raw output is requested. Valid formats are +.IR yuv , +.IR rgb , +and +.IR grey . +.I grey +simply saves the Y channel of the YUV image. +. +.TP +.BR \-pts ", " \-\-save-pts " \fIfilename\fR" +Saves timestamp information to the specified file. Useful as an input file to +.BR mkvmerge (1). +. +.TP +.BR \-sg ", " \-\-segment " \fIms\fR" +Rather than creating a single file, the file is split into segments of +approximately the number of milliseconds specified. In order to provide +different filenames, you should add +.I %04d +or similar at the point in the filename where you want a segment count number +to appear e.g: +.IP +.EX +\-\-segment 3000 \-o video%04d.h264 +.EE +.IP +will produce video clips of approximately 3000ms (3s) long, named +\(lqvideo0001.h264\(rq, \(lqvideo0002.h264\(rq etc. The clips should be +seamless (no frame drops between clips), but the accuracy of each clip length +will depend on the intraframe period, as the segments will always start on an +I-frame. They will therefore always be equal or longer to the specified period. +.IP +The most recent version of +.B raspivid +will also allow the file name to be time-based, rather than using a segment +number. For example: +.IP +.EX +\-\-segment 3000 \-o video_%c.h264 +.EE +.IP +will produce file names formatted like so: +\(lqvideo_Fri Jul 20 16:23:48 2018.h264\(rq +.IP +There are many different formatting options available - see +.BR strftime (3) +for a full list. Note than the +.I %d +and +.I %u +options are not available, as they are used for the segment number formatting, +and that some combinations may produce invalid file names. +. +.TP +.BR \-s ", " \-\-signal +Sending a +.I USR1 +signal to the +.B raspivid +process will toggle between recording and paused. This can be done using the +.BR killall (1) +command, as below: +.IP +.EX +killall -USR1 raspivid +.EE +.IP +Note that the timeout value will be used to indicate the end of recording, but +is only checked after each receipt of the +.I USR1 +signal; so if the system is waiting for a signal, even if the timeout has +expired, it will still wait for the signal before exiting. +. +.TP +.BR \-sl ", " \-\-slices " \fInum\fR" +Sets the number of horizontal slices per frame. The default is 1 (no slices). +. +.TP +.BR \-sp ", " \-\-split +When in +.I \-\-signal +or +.I \-\-keypress +mode, each time recording is restarted, a new file is created. +. +.TP +.BR \-stm ", " \-\-spstimings +Insert timing information into the SPS block. +. +.TP +.BR \-sn ", " \-\-start " \fInum\fR" +When outputting segments (with +.IR \-\-segment ), +this is the initial segment number, giving the ability to resume a previous +recording from a given segment. The default value is 1. +. +.TP +.BR \-td ", " \-\-timed " \fIon,off\fR" +This options allows the video capture to be paused and restarted at particular +time intervals. Two values are required: the on time and the off time, both +measured in milliseconds. On time is the amount of time the video is captured, +and off time is the amount it is paused. The total runtime of the application +is defined by the timeout option +.RI ( \-t ). +Note that the runtime may go slightly over the timeout setting depending on the +on and off times. +.IP +For example: +.IP +.EX +raspivid \-o test.h264 \-t 25000 \-\-timed 2500,5000 +.EE +.IP +This will alternate between recording for 2500ms (2.5s), then pausing for +5000ms (5s) gaps, until 25000ms (25s) have elapsed. The resulting recording +will only be 10s long, since 4 segments of 2.5s = 10s, separated by 3 gaps of +5s = 15s, for a total of 25s: +.IP +.EX +Seconds 1 2 + 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +RRRRR..........RRRRR..........RRRRR..........RRRRR +.EE +. +.TP +.BR \-t ", " \-\-timeout " \fIms\fR" +The total length of time that the program will run for. If not specified, the +default is 5000ms (5 seconds). If set to 0, the application will run +indefinitely until stopped with Ctrl-C. +. +.TP +.BR \-x ", " \-\-vectors " \fIfilename\fR" +Turns on output of motion vectors from the H264 encoder to the specified file +name. +. +.TP +.BR \-v ", " \-\-verbose +Outputs debugging/information messages during the program run. +. +.TP +.BR \-wr ", " \-\-wrap " \fInum\fR" +When outputting segments, this is the maximum the segment number can reach +before it's reset to 1, giving the ability to keep recording segments, but +overwriting the oldest one. So if set to 4, in the +.I \-\-segment +example above, the files produced will be \(lqvideo0001.h264\(rq, +\(lqvideo0002.h264\(rq, \(lqvideo0003.h264\(rq, and \(lqvideo0004.h264\(rq. +Once \(lqvideo0004.h264\(rq is recorded, the count will reset to 1, and +\(lqvideo0001.h264\(rq will be overwritten. +. +. +.SH EXIT STATUS +. +.IP 0 +Application ran successfully +.RB ( EX_OK ) +.IP 64 +Bad command line parameter +.RB ( EX_USAGE ) +.IP 70 +Software or camera error +.RB ( EX_SOFTWARE ) +.IP 130 +Application terminated by Ctrl-C +. +. +.SH EXAMPLES +. +Image size and preview settings are the same as for still captures. The default +size for video recording is 1080p (1920x1080). +. +.TP +.B raspivid \-t 5000 \-o video.h264 +Record a 5s clip with default settings (1080p30). +. +.TP +.B raspivid \-t 5000 \-o video.h264 \-b 3500000 +Record a 5s clip at a specified bitrate (3.5Mbits/s). +. +.TP +.B raspivid \-t 5000 \-o video.h264 \-f 5 +Record a 5s clip at a specified framerate (5fps). +. +.TP +.B raspivid \-t 5000 \-o \- +Encode a 5s camera stream and send the image data to stdout. +. +.TP +.B raspivid \-t 5000 \-o \- > my_file.h264 +Encode a 5s camera stream and send the image data to a file. +. +. +.SH SEE ALSO +.BR raspicam (7), +.BR raspistill (1), +.BR raspividyuv (1), +.BR raspiyuv (1), +.BR vcgencmd (1), +.B [SOURCE] +. +. +.SH REFERENCES +.TP +.B [SOURCE] +https://www.raspberrypi.org/\:documentation/\:raspbian/\:applications/\:camera.md diff --git a/host_applications/linux/apps/raspicam/raspividyuv.1 b/host_applications/linux/apps/raspicam/raspividyuv.1 new file mode 100644 index 000000000..fd8e02903 --- /dev/null +++ b/host_applications/linux/apps/raspicam/raspividyuv.1 @@ -0,0 +1,276 @@ +.TH RASPIVIDYUV 1 +. +.SH NAME +raspividyuv \- records unencoded video with the Pi Camera Module +. +. +.SH SYNOPSIS +.SY raspividyuv +.OP \-3d mode +.OP \-3dswap +.OP \-ISO value +.OP \-a flags|text +.OP \-ae size,fg,bg +.OP \-ag value +.OP \-awb mode +.OP \-awbg b,r +.OP \-br value +.OP \-cfx u:v +.OP \-co value +.OP \-cs camera +.OP \-d ms +.OP \-dg value +.OP \-dn screen +.OP \-drc value +.OP \-ev value +.OP \-ex mode +.OP \-f +.OP \-fli mode +.OP \-fps fps +.OP \-gps +.OP \-h size +.OP \-hf +.OP \-i state +.OP \-ifx effect +.OP \-k +.OP \-l +.OP \-md mode +.OP \-mm mode +.OP \-n +.OP \-o filename +.OP \-op opacity +.OP \-p x,y,w,h +.OP \-pts filename +.OP \-roi x,y,w,h +.OP \-rot value +.OP \-s +.OP \-sa value +.OP \-set +.OP \-sh value +.OP \-ss value +.OP \-t ms +.OP \-td on,off +.OP \-v +.OP \-vf +.OP \-w size +.YS +. +.SY raspividyuv +.OP \-? +.SY raspividyuv +.OP \-\-help +.YS +. +. +.SH DESCRIPTION +.B raspividyuv +is a command line utility for recording unencoded video frames from the +Raspberry Pi Camera Module (any version), in YUV format by default (see +.BR [YUV] ). +It has numerous options which can be used to customize the recording, the +preview display, or to perform more complex operations like video streaming. +. +. +.SH OPTIONS +The options documented in the following sections are specific to the +.B raspividyuv +utility, or commonly used with it. For full details of the other options (which +are common to all the camera utilities), please refer to the +.BR raspicam (7) +manual page. +. +. +.SH GENERAL OPTIONS +. +.TP +.BR \-? ", " \-\-help +Display a concise description of all parameters +. +.TP +.BR \-d ", " \-\-demo " [\fIms\fR]" +This options cycles through the range of camera options. No recording is taken, +and the demo will end at the end of the timeout period, irrespective of whether +all the options have been cycled. The time between cycles should be specified +as a millisecond value. +. +.TP +.BR \-fps ", " \-\-framerate " \fIfps\fR" +Specifies the frames per second to record. At present, the minimum frame rate +allowed is 2fps, and the maximum is 30fps. This is likely to change in the +future. +. +.TP +.BR \-h ", " \-\-height " \fIsize\fR" +Set the video height to +.IR size . +. +.TP +.BR \-i ", " \-\-initial " \fIstate\fR" +Define whether the camera will start paused or will immediately start +recording. Valid states are +.I record +or +.IR pause . +Note that if you are using a simple timeout (without +.I \-\-timed +or +.I \-\-keypress +or other options to activate recording), and +.I \-\-initial +is set to +.IR pause , +no output will be recorded. +. +.TP +.BR \-k ", " \-\-keypress +On each press of the Enter key, the recording will be paused or restarted. +Pressing X then Enter will stop recording and close the application. Note that +the timeout value +.RI ( \-t ) +will be used to signal the end of recording, but is only checked after each +Enter keypress; so if the system is waiting for a keypress, even if the timeout +has expired, it will still wait for the keypress before exiting. +. +.TP +.BR \-l ", " \-\-listen +When using a network connection as the +.IR \-\-output , +this option will make the sytem wait for a connection from the remote system +before sending data. +. +.TP +.BR \-y ", " \-\-luma +Only outputs the luma (Y) channel of the YUV image. This is effectively the +black and white, or intensity, part of the image. See +.B [YUV] +for more information. +. +.TP +.BR \-o ", " \-\-output " \fIfilename\fR" +Specify the output filename. If not specified, no file is saved. If the +filename is \(lq\-\(rq, then all output is sent to stdout. +. +To connect to a remote IPv4 host, use +.I tcp +or +.I udp +followed by the required IP Address. e.g. +.I tcp://192.168.1.2:1234 +or +.IR udp://192.168.1.2:1234 . +.IP +To listen on a TCP port (IPv4) and wait for an incoming connection use the +.I \-\-listen +option, e.g. +.I raspividyuv \-l \-o tcp://0.0.0.0:3333 +will bind to all network interfaces, +.I raspividyuv \-l \-o tcp://192.168.1.1:3333 +will bind to a local IPv4. +. +.TP +.BR \-pts ", " \-\-save-pts " \fIfilename\fR" +Saves timestamp information to the specified file. Useful as an input file to +.BR mkvmerge (1). +. +.TP +.BR \-rgb ", " \-\-rgb +This option forces the video to be saved as RGB data with 8 bits per channel, +rather than YUV420. +. +Note that the video frames saved in +.B raspividyuv +are padded to a horizontal size divisible by 32, so there may be unused bytes +at the end of each line. Buffers are also padded vertically to be divisible by +16, and in the YUV mode, each plane of Y,U,V is padded in this way. +. +.TP +.BR \-s ", " \-\-signal +Sending a +.I USR1 +signal to the +.B raspividyuv +process will toggle between recording and paused. This can be done using the +.BR killall (1) +command, as below: +.IP +.EX +killall -USR1 raspividyuv +.EE +.IP +Note that the timeout value will be used to indicate the end of recording, but +is only checked after each receipt of the +.I USR1 +signal; so if the system is waiting for a signal, even if the timeout has +expired, it will still wait for the signal before exiting. +. +.TP +.BR \-td ", " \-\-timed " \fIon,off\fR" +This options allows the video capture to be paused and restarted at particular +time intervals. Two values are required: the on time and the off time, both +measured in milliseconds. On time is the amount of time the video is captured, +and off time is the amount it is paused. The total runtime of the application +is defined by the timeout option +.RI ( \-t ). +Note that the runtime may go slightly over the timeout setting depending on the +on and off times. +.IP +For example: +.IP +.EX +raspividyuv \-o test.h264 \-t 25000 \-\-timed 2500,5000 +.EE +.IP +This will alternate between recording for 2500ms (2.5s), then pausing for +5000ms (5s) gaps, until 25000ms (25s) have elapsed. The resulting recording +will only be 10s long, since 4 segments of 2.5s = 10s, separated by 3 gaps of +5s = 15s, for a total of 25s: +.IP +.EX +Seconds 1 2 + 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +RRRRR..........RRRRR..........RRRRR..........RRRRR +.EE +. +.TP +.BR \-t ", " \-\-timeout " \fIms\fR" +The total length of time that the program will run for. If not specified, the +default is 5000ms (5 seconds). If set to 0, the application will run +indefinitely until stopped with Ctrl-C. +. +.TP +.BR \-v ", " \-\-verbose +Outputs debugging/information messages during the program run. +. +. +.SH EXIT STATUS +. +.IP 0 +Application ran successfully +.RB ( EX_OK ) +.IP 64 +Bad command line parameter +.RB ( EX_USAGE ) +.IP 70 +Software or camera error +.RB ( EX_SOFTWARE ) +.IP 130 +Application terminated by Ctrl-C +. +. +.SH SEE ALSO +.BR raspicam (7), +.BR raspistill (1), +.BR raspivid (1), +.BR raspiyuv (1), +.BR vcgencmd (1), +.B [SOURCE] +. +. +.SH REFERENCES +.TP +.B [SOURCE] +https://www.raspberrypi.org/\:documentation/\:raspbian/\:applications/\:camera.md +. +.TP +.B [YUV] +https://en.wikipedia.org/wiki/YUV diff --git a/host_applications/linux/apps/raspicam/raspiyuv.1 b/host_applications/linux/apps/raspicam/raspiyuv.1 new file mode 100644 index 000000000..a13bc62ab --- /dev/null +++ b/host_applications/linux/apps/raspicam/raspiyuv.1 @@ -0,0 +1,234 @@ +.TH RASPIYUV 1 +. +.SH NAME +raspiyuv \- takes unencoded still captures with the Pi Camera Module +. +. +.SH SYNOPSIS +.SY raspiyuv +.OP \-3d mode +.OP \-3dswap +.OP \-a flags|text +.OP \-ae size,fg,bg +.OP \-ag value +.OP \-awb mode +.OP \-awbg b,r +.OP \-bm +.OP \-br value +.OP \-cfx u:v +.OP \-co value +.OP \-cs camera +.OP \-dec +.OP \-dg value +.OP \-dn screen +.OP \-drc value +.OP \-ev value +.OP \-ex mode +.OP \-f +.OP \-fli mode +.OP \-fp +.OP \-gps +.OP \-h size +.OP \-hf +.OP \-ifx effect +.OP \-ISO value +.OP \-k +.OP \-l filename +.OP \-md mode +.OP \-mm mode +.OP \-n +.OP \-o filename +.OP \-op opacity +.OP \-p x,y,w,h +.OP \-roi x,y,w,h +.OP \-rot value +.OP \-s +.OP \-sa value +.OP \-set +.OP \-sh value +.OP \-ss value +.OP \-st +.OP \-t ms +.OP \-tl ms +.OP \-v +.OP \-vf +.OP \-w size +.YS +. +.SY raspiyuv +.OP \-? +.SY raspiyuv +.OP \-\-help +.YS +. +. +.SH DESCRIPTION +.B raspiyuv +is a command line utility for capturing unencoded still images from the +Raspberry Pi Camera Module (any version), in YUV format by default (see +.BR [YUV] ). +It has numerous options which can be used to customize the capture process, the +preview display, or to perform more complex operations like time-lapse or +triggered captures. +. +. +.SH OPTIONS +The options documented in the following sections are specific to the +.B raspiyuv +utility, or commonly used with it. For full details of the other options (which +are common to all the camera utilities), please refer to the +.BR raspicam (7) +manual page. +. +. +.SH GENERAL OPTIONS +. +.TP +.BR \-? ", " \-\-help +Display a concise description of all parameters +. +.TP +.BR \-bgr ", " \-\-bgr +Saves the image data as BGR data rather than YUV. See +.B \-\-rgb +below for more information. +. +.TP +.BR \-bm ", " \-\-burst +Sets burst capture mode. This prevents the camera from returning to preview +mode in between captures, meaning that captures can be taken closer together. +. +.TP +.BR \-fp ", " \-\-fullpreview +This runs the preview using the full resolution capture mode. Maximum frames +per second in this mode is 15fps, and the preview will have the same field of +view as the capture. Captures should happen more quickly, as no mode change +should be required. This feature is currently under development. +. +.TP +.BR \-h ", " \-\-height " \fIsize\fR" +Set the image height to +.IR size . +. +.TP +.BR \-k ", " \-\-keypress +The camera is run for the requested time +.RI ( \-t ), +and a capture can be initiated throughout that time by pressing the Enter key. +Pressing X then Enter will exit the application before the timeout is reached. +If the timeout is set to 0, the camera will run indefinitely until the user +presses X then Enter. Using the verbose option +.RI ( \-v ) +will display a prompt asking for user input, otherwise no prompt is displayed. +. +.TP +.BR \-l ", " \-\-latest " \fIfilename\fR" +Makes a file system link under this name to the latest frame. +. +.TP +.BR \-y ", " \-\-luma +Only outputs the luma (Y) channel of the YUV image. This is effectively the +black and white, or intensity, part of the image. See +.B [YUV] +for more information. +. +.TP +.BR \-o ", " \-\-output " \fIfilename\fR" +Specifies the output filename. If not specified, no file is saved. +If the filename is \(lq\-\(rq, then all output is send to stdout. +. +.TP +.BR \-rgb ", " \-\-rgb +This option forces the image to be saved as RGB data with 8 bits per channel, +rather than YUV420. +. +Note that the image buffers saved in +.B raspiyuv +are padded to a horizontal size divisible by 32, so there may be unused bytes +at the end of each line. Buffers are also padded vertically to be divisible by +16, and in the YUV mode, each plane of Y,U,V is padded in this way. +. +.TP +.BR \-s ", " \-\-signal +The camera is run for the requested time +.RI ( -t ), +and a capture can be initiated throughout that time by sending a USR1 signal to +the camera process. This can be done using the +.BR killall (1) +command. For example: +.IP +.EX +killall -USR1 raspiyuv +.EE +. +.TP +.BR \-v ", " \-\-verbose +Outputs debugging/information messages during the program run. +. +.TP +.BR \-w ", " \-\-width " \fIsize\fR" +Set the image width to +.IR size . +. +. +.SH TIMELAPSE OPTIONS +. +.TP +.BR \-tl ", " \-\-timelapse " \fIms\fR" +The specific value is the time between shots in milliseconds. Note that you +should specify +.I %04d +at the point in the filename where you want a frame count number to appear. So, +for example, the code below will produce a capture every 2 seconds, over a +total period of 30s, named \(lqimage0001.jpg\(rq, \(lqimage0002.jpg\(rq and so +on, through to \(lqimage0015.jpg\(rq: +.IP +.EX +-t 30000 -tl 2000 -o image%04d.jpg +.EE +.IP +Note that the +.I %04d +indicates a 4-digit number, with leading zeroes added to make the required +number of digits. So, for example, +.I %08d +would result in an 8-digit number. +. +If a timelapse value of 0 is entered, the application will take pictures as +fast as possible. Note that there's an minimum enforced pause of 30ms between +captures to ensure that exposure calculations can be made. +. +. +.SH EXIT STATUS +. +.IP 0 +Application ran successfully +.RB ( EX_OK ) +.IP 64 +Bad command line parameter +.RB ( EX_USAGE ) +.IP 70 +Software or camera error +.RB ( EX_SOFTWARE ) +.IP 130 +Application terminated by Ctrl-C +. +. +.SH SEE ALSO +.BR raspicam (7), +.BR raspistill (1), +.BR raspivid (1), +.BR raspividyuv (1), +.BR vcgencmd (1), +.B [YUV], +.B [SOURCE] +. +. +.SH REFERENCES +.TP +.B [SOURCE] +https://www.raspberrypi.org/\:documentation/\:raspbian/\:applications/\:camera.md +. +.TP +.B [YUV] +https://en.wikipedia.org/wiki/YUV diff --git a/host_applications/linux/apps/tvservice/CMakeLists.txt b/host_applications/linux/apps/tvservice/CMakeLists.txt index f5b19eed3..650684248 100644 --- a/host_applications/linux/apps/tvservice/CMakeLists.txt +++ b/host_applications/linux/apps/tvservice/CMakeLists.txt @@ -3,3 +3,4 @@ target_link_libraries(tvservice vchostif) install(TARGETS tvservice RUNTIME DESTINATION bin) +install(FILES tvservice.1 DESTINATION man/man1) diff --git a/host_applications/linux/apps/tvservice/tvservice.1 b/host_applications/linux/apps/tvservice/tvservice.1 new file mode 100644 index 000000000..aa9bc8bcd --- /dev/null +++ b/host_applications/linux/apps/tvservice/tvservice.1 @@ -0,0 +1,155 @@ +.TH TVSERVICE 1 +. +.SH NAME +tvservice \- get and set information from attached displays +. +. +.SH SYNOPSIS +.SY tvservice +.OP \-a +.OP \-c "mode aspect p" +.OP \-d filename +.OP \-e "group mode drive" +.OP \-j +.OP \-l +.OP \-m group +.OP \-M +.OP \-n +.OP \-o +.OP \-p +.OP \-s +.OP \-t +.OP \-v id +.YS +. +.SY tvservice +.B \-h +.SY tvservice +.B \-\-help +.YS +. +. +.SH DESCRIPTION +.B tvservice +is a command line application used to get and set information about the +display, targeted mainly at HDMI video and audio. +. +Typing +.B tvservice +by itself will display a list of available command line options. +. +. +.SH OPTIONS +. +.TP +.BR \-a ", " \-\-audio +Shows the current settings for the audio mode, including channels, sample rate +and sample size. +. +.TP +.BR \-c ", " \-\-sdtvon " \(dq\fImode aspect \fR[\fIP\fR]\(dq" +Power on the SDTV (composite output) with the specified +.IR mode , +PAL or NSTC, and the specified +.IR aspect , +4:3, 14:9, 16:9. The optional \(lqP\(rq parameter can be used to specify +progressive mode. +. +.TP +.BR \-d ", " \-\-dumpid " \fIfilename\fR" +Save the current EDID to the specified filename. You can then use +.BR edid-decode (1) +to display the data in a human readable form. See +.B [EDID] +for more information on the EDID contents. +. +.TP +.BR \-e ", " \-\-explicit " \(dq\fIgroup mode drive\fR\(dq" +Power on the HDMI display with the specified settings. +. +The +.I group +option can be one of CEA, DMT, CEA_3D_SBS, CEA_3D_TB, CEA_3D_FP, or CEA_3D_FS; +.I mode +is one of the modes returned from the +.B \-\-modes +option. Finally, +.I drive +can be HDMI or DVI. +. +.TP +.BR \-j ", " \-\-json +When used in combination with the +.B \-\-modes +option, displays the mode information in JSON format. +. +.TP +.BR \-l ", " \-\-list +Lists all attached displays and their display ID. +. +.TP +.BR \-m ", " \-\-modes " \fIgroup\fR" +Shows a list of display modes available in the specified +.IR group , +which can be either CEA or DMT. +. +.TP +.BR \-M ", " \-\-monitor +Monitors for any HDMI events, for example unplugging or attaching. +. +.TP +.BR \-n ", " \-\-name +Extracts the display name from the EDID data and shows it. +. +.TP +.BR \-o ", " \-\-off +Powers off the display output. +.IP +.B Important Note: +Powering off the output using this command will also destroy any +framebuffers/dispmanx layers associated with the display. These are NOT +re-established with a subsequent power on, so will result in a blank screen. +.IP +A better option is to use the +.BR vcgencmd (1) +.B display_power +option, as this will retain any framebuffers, so when the power is turned back +on the display will be the returned to the previous power on state. +. +.TP +.BR \-p ", " \-\-preferred +Power on the HDMI output with preferred settings. +. +.TP +.BR \-s ", " \-\-status +Shows the current settings for the display mode, including mode, resolution, +and frequency. +. +.TP +.BR \-t ", " \-\-ntsc +Use 59.94Hz (NTSC frequency) rather than 60Hz for HDMI mode. +. +.TP +.BR \-v ", " \-\-device " \fIid\fR" +Specifies the ID of the device to use; see the output of +.B \-\-list +for available IDs. +. +. +.SH SEE ALSO +.BR vcgencmd (1), +.BR edid-decode (1) +. +.PP +Full documentation at +.BR [SOURCE] . +. +. +.SH REFERENCES +.TP +.B [EDID] +https://en.wikipedia.org/wiki/Extended_Display_Identification_Data +. +.TP +.B [SOURCE] +https://www.raspberrypi.org/documentation/raspbian/applications/tvservice.md diff --git a/host_applications/linux/apps/vcmailbox/CMakeLists.txt b/host_applications/linux/apps/vcmailbox/CMakeLists.txt index 016a4d9c0..d153363ca 100644 --- a/host_applications/linux/apps/vcmailbox/CMakeLists.txt +++ b/host_applications/linux/apps/vcmailbox/CMakeLists.txt @@ -3,3 +3,5 @@ target_link_libraries(vcmailbox vchostif) install(TARGETS vcmailbox RUNTIME DESTINATION bin) +install(FILES vcmailbox.1 DESTINATION man/man1) +install(FILES vcmailbox.7 raspiotp.7 raspirev.7 DESTINATION man/man7) diff --git a/host_applications/linux/apps/vcmailbox/raspiotp.7 b/host_applications/linux/apps/vcmailbox/raspiotp.7 new file mode 100644 index 000000000..3341d9939 --- /dev/null +++ b/host_applications/linux/apps/vcmailbox/raspiotp.7 @@ -0,0 +1,228 @@ +.TH RASPIOTP 7 +. +.SH NAME +raspiotp \- the Raspberry Pi OTP register bits +. +. +.SH DESCRIPTION +. +All SoCs used by the Raspberry Pi range have a inbuilt One-Time Programmable +(OTP) memory block. +It is 66 32-bit values long, although only a few locations have +factory-programmed data. +The +.BR vcgencmd (1) +utility can be used to display the contents of the OTP like so: +.PP +.EX +$ \fBvcgencmd otp_dump\fR +.EE +. +. +.SH OTP REGISTERS +This list contains the publicly available information on the registers. If a +register or bit is not defined here, then it is not public. +. +.TP +.B 17 +bootmode register +.RS +.TP +.B Bit 1 +sets the oscillator frequency to 19.2MHz +.TP +.B Bit 3 +enables pull ups on the SDIO pins +.TP +.B Bit 19 +enables GPIO bootmode +.TP +.B Bit 20 +sets the bank to check for GPIO bootmode +.TP +.B Bit 21 +enables booting from SD card +.TP +.B Bit 22 +sets the bank to boot from +.TP +.B Bit 28 +enables USB device booting +.TP +.B Bit 29 +enables USB host booting (ethernet and mass storage) +.RE +. +.TP +.B 18 +copy of bootmode register +. +.TP +.B 28 +serial number +. +.TP +.B 29 +~(serial number) +. +.TP +.B 30 +revision code; +. +.BR raspirev (7) +.TP +.B 36-43 +customer OTP values (see +.B INDUSTRIAL USE +below) +. +.TP +.B 45 +MPG2 decode key +. +.TP +.B 46 +WVC1 decode key +. +.TP +.B 64-65 +MAC address; if set, system will use this in preference to the automatically generated address based on the serial number +. +.TP +.B 66 +advanced boot register +.RS +.TP +.B Bits 0-6 +GPIO for ETH_CLK output pin +.TP +.B Bit 7 +enables ETH_CLK output +.TP +.B Bits 8-14 +GPIO for LAN_RUN output pin +.TP +.B Bit 15 +enables LAN_RUN output +.TP +.B Bit 24 +extends USB HUB timeout parameter +.TP +.B Bit 25 +ETH_CLK frequency: 0=25MHz, 1=24MHz +.RE +. +. +.SH INDUSTRIAL USE +The Raspberry Pi is often used as part of another product. This section +describes some extra facilities available to use other capabilities of the Pi. +. +.SS Customer OTP settings +There are a number of OTP values that can be used. To see a list of all the OTP +values, you can use: +.PP +.EX +$ \fBvcgencmd otp_dump\fR +.EE +.PP +In register locations 36 to 43 (inclusive), there are eight rows of 32 bits +available for the customer (detailed in +.B OTP REGISTERS +above). +.PP +To program these bits, you will need to use the vcmailbox. This is a Linux +driver interface to the firmware which will handle the programming of the rows. +To do this, please refer to the documentation at [MAILBOX], and the +.BR vcmailbox (1) +example application. For example: +.PP +.EX +$ \fBvcmailbox 0x00010004 8 8 0 0\fR +0x00000020 0x80000000 0x00010004 0x00000008 0x800000008 0xnnnnnnnn +0x00000000 0x00000000 +.EE +.PP +The above uses the +.B GET_BOARD_SERIAL +tag (detailed under [MAILBOX]) with a request size of 8 bytes and response +size of 8 bytes (sending two integers for the request 0, 0). The response to +this will be two integers (0x00000020 and 0x80000000) followed by the tag code, +the request length, the response length (with the 31st bit set to indicate that +it is a response) then the 64 bit serial number (where the MS 32bits are always +0). +.PP +To set the customer OTP values you will need to use the +.B SET_CUSTOMER_OTP +(0x38021) tag as follows: +.PP +.EX +$ \fBvcmailbox 0x00038021 \fI[8+rows*4] [8+rows*4] [start] [rows] [value]\fR ... +.EE +.TP +.B start +the first row to program from 0-7 +.TP +.B rows +number of rows to program +.TP +.B value +each value to program +.PP +So, to program OTP customer rows 4, 5, and 6 to 0x11111111, 0x22222222, +0x33333333 respectively, you would use: +.PP +.EX +$ \fBvcmailbox 0x00038021 20 20 4 3 0x11111111 0x22222222 0x33333333\fR +.EE +.PP +This will then program rows 40, 41, and 42. To read the values back, you can +use: +.PP +.EX +$ \fBvcmailbox 0x00030021 20 20 4 3 0 0 0\fR +0x0000002c 0x80000000 0x00030021 0x00000014 0x80000014 0x00000000 +0x00000003 0x11111111 0x22222222 0x33333333 +.EE +.PP +If you'd like to integrate this functionality into your own code, you should be +able to achieve this by using the vcmailbox.c code as an example. +. +.SS Locking the OTP changes +It is possible to lock the OTP changes to avoid them being edited again. This +can be done using a special argument with the OTP write mailbox: +.PP +.EX +$ \fBvcmailbox 0x00038021 8 8 0xffffffff 0xaffe0000\fR +.EE +.PP +Once locked, the customer OTP values can no longer be altered. Note that this +locking operation is irreversible. +. +.SS Making customer OTP bits unreadable +It is possible to prevent the customer OTP bits from being read at all. This +can be done using a special argument with the OTP write mailbox: +.PP +.EX +$ \fBvcmailbox 0x00038021 8 8 0xffffffff 0xaffebabe\fR +.EE +.PP +This operation is unlikely to be useful for the vast majority of users, and is +irreversible. +. +. +.SH SEE ALSO +.BR vcgencmd (1), +.BR raspirev (7), +.B [SOURCE] +. +. +.SH REFERENCES +.TP +.B [MAILBOX] +https://github.com/raspberrypi/firmware/wiki/Mailbox-property-interface +. +.TP +.B [SOURCE] +https://www.raspberrypi.org/documentation/hardware/raspberrypi/otpbits.md +and +https://www.raspberrypi.org/documentation/hardware/industrial/README.md diff --git a/host_applications/linux/apps/vcmailbox/raspirev.7 b/host_applications/linux/apps/vcmailbox/raspirev.7 new file mode 100644 index 000000000..01cd8fa71 --- /dev/null +++ b/host_applications/linux/apps/vcmailbox/raspirev.7 @@ -0,0 +1,332 @@ +.TH RASPIREV 7 +. +.SH NAME +raspirev \- Raspberry Pi revision codes +. +. +.SH DESCRIPTION +Each distinct Raspberry Pi model revision has a unique revision code. You can +look up a Raspberry Pi's revision code by running: +.PP +.EX +$ \fBcat /proc/cpuinfo\fR +.EE +.PP +The last three lines show the hardware type, the revision code, and the Pi's +unique serial number. For example: +.PP +.EX +Hardware : BCM2835 +Revision : a02082 +Serial : 00000000765fc593 +.EE +.PP +.B Note: +As of the 4.9 kernel, all Pis report BCM2835, even those with BCM2836, BCM2837 +and BCM2711 processors. You should not use this string to detect the processor. +Decode the revision code using the information below, or read +.I /sys/firmware/devicetree/base/model +. +. +.SH OLD-STYLE REVISION CODES +The first set of Raspberry Pi models were given sequential hex revision codes +from 0002 to 0015: +.TS +tab(|); +l l l l l . +Code|Model|Revision|RAM|Manufacturer +\_|\_|\_|\_|\_ +0002|B|1.0|256MB|Egoman +0003|B|1.0|256MB|Egoman +0004|B|2.0|256MB|Sony UK +0005|B|2.0|256MB|Qisda +0006|B|2.0|256MB|Egoman +0007|A|2.0|256MB|Egoman +0008|A|2.0|256MB|Sony UK +0009|A|2.0|256MB|Qisda +000d|B|2.0|512MB|Egoman +000e|B|2.0|512MB|Sony UK +000f|B|2.0|512MB|Egoman +0010|B+|1.2|512MB|Sony UK +0011|CM1|1.0|512MB|Sony UK +0012|A+|1.1|256MB|Sony UK +0013|B+|1.2|512MB|Embest +0014|CM1|1.0|512MB|Embest +0015|A+|1.1|256MB/512MB|Embest +.TE +. +. +.SH NEW-STYLE REVISION CODES +With the launch of the Raspberry Pi 2, new-style revision codes were +introduced. Rather than being sequential, each bit of the hex code represents a +piece of information about the revision: +.PP +.EX +NOQuuuWuFMMMCCCCPPPPTTTTTTTTRRRR +.EE +. +.TP +.B N +Overvoltage +.PD 0 +.RS +.TP +.B 0 +Overvoltage allowed +.TP +.B 1 +Overvoltage disallowed +.RE +.PD +. +.TP +.B O +OTP Programming; see +.BR raspiotp (7) +.PD 0 +.RS +.TP +.B 0 +OTP programming allowed +.TP +.B 1 +OTP programming disallowed +.RE +.PD +. +.TP +.B Q +OTP Reading; see +.BR raspiotp (7) +.PD 0 +.RS +.TP +.B 0 +OTP reading allowed +.TP +.B 1 +OTP reading disallowed +.RE +.PD +. +.TP +.BR uuu +Unused +. +.TP +.B W +Warranty bit +.PD 0 +.RS +.TP +.B 0 +Warranty is intact +.TP +.B 1 +Warranty has been voided by overclocking +.RE +.PD +. +.TP +.B u +Unused +. +.TP +.B F +New flag +.PD 0 +.RS +.TP +.B 1 +new-style revision +.TP +.B 0 +old-style revision +.RE +.PD +. +.TP +.B MMM +Memory size +.PD 0 +.RS +.TP +.B 0 +256MB +.TP +.B 1 +512MB +.TP +.B 2 +1GB +.TP +.B 3 +2GB +.TP +.B 4 +4GB +.TP +.B 5 +8GB +.RE +.PD +. +.TP +.B CCCC +Manufacturer +.PD 0 +.RS +.TP +.B 0 +Sony UK +.TP +.B 1 +Egoman +.TP +.B 2 +Embest +.TP +.B 3 +Sony Japan +.TP +.B 4 +Embest +.TP +.B 5 +Stadium +.RE +.PD +. +.TP +.B PPPP +Processor +.PD 0 +.RS +.TP +.B 0 +BCM2835 +.TP +.B 1 +BCM2836 +.TP +.B 2 +BCM2837 +.TP +.B 3 +BCM2711 +.RE +.PD +. +.TP +.B TTTTTTTT +Type +.PD 0 +.RS +.TP +.B 0 +A +.TP +.B 1 +B +.TP +.B 2 +A+ +.TP +.B 3 +B+ +.TP +.B 4 +2B +.TP +.B 5 +Alpha (early prototype) +.TP +.B 6 +CM1 +.TP +.B 8 +3B +.TP +.B 9 +Zero +.TP +.B a +CM3 +.TP +.B c +Zero W +.TP +.B d +3B+ +.TP +.B e +3A+ +.TP +.B f +Internal use only +.TP +.B 10 +CM3+ +.TP +.B 11 +4B +.TP +.B 13 +400 +.TP +.B 14 +CM4 +.RE +.PD +. +.TP +.B RRRR +Revision (0, 1, 2, etc.) +.PP +New-style revision codes in use at the time of writing: +.TS +tab(|); +l l l l l . +Code|Model|Revision|RAM|Manufacturer +\_|\_|\_|\_|\_ +900021|A+|1.1|512MB|Sony UK +900032|B+|1.2|512MB|Sony UK +900092|Zero|1.2|512MB|Sony UK +900093|Zero|1.3|512MB|Sony UK +9000c1|Zero W|1.1|512MB|Sony UK +9020e0|3A+|1.0|512MB|Sony UK +920092|Zero|1.2|512MB|Embest +920093|Zero|1.3|512MB|Embest +900061|CM|1.1|512MB|Sony UK +a01040|2B|1.0|1GB|Sony UK +a01041|2B|1.1|1GB|Sony UK +a02082|3B|1.2|1GB|Sony UK +a020a0|CM3|1.0|1GB|Sony UK +a020d3|3B+|1.3|1GB|Sony UK +a02042|2B (BCM2837)|1.2|1GB|Sony UK +a21041|2B|1.1|1GB|Embest +a22042|2B (BCM2837)|1.2|1GB|Embest +a22082|3B|1.2|1GB|Embest +a220a0|CM3|1.0|1GB|Embest +a32082|3B|1.2|1GB|Sony Japan +a52082|3B|1.2|1GB|Stadium +a22083|3B|1.3|1GB|Embest +a02100|CM3+|1.0|1GB|Sony UK +a03111|4B|1.1|1GB|Sony UK +b03111|4B|1.1|2GB|Sony UK +b03112|4B|1.2|2GB|Sony UK +c03111|4B|1.1|4GB|Sony UK +c03112|4B|1.2|4GB|Sony UK +d03114|4B|1.4|8GB|Sony UK +.TE +. +. +.SH SEE ALSO +.BR raspiotp (7), +.B [SOURCE] +. +. +.SH REFERENCES +.TP +.B [SOURCE] +https://www.raspberrypi.org/documentation/hardware/raspberrypi/revision-codes/README.md diff --git a/host_applications/linux/apps/vcmailbox/vcmailbox.1 b/host_applications/linux/apps/vcmailbox/vcmailbox.1 new file mode 100644 index 000000000..66a2c1a23 --- /dev/null +++ b/host_applications/linux/apps/vcmailbox/vcmailbox.1 @@ -0,0 +1,35 @@ +.TH VCMAILBOX 1 +. +.SH NAME +vcmailbox \- send messages to the VideoCore via the mailbox +. +. +.SH SYNOPSIS +.SY vcmailbox +.RI [ word0 ] +.RI [ word1 ] +\|.\|.\|. +. +. +.SH DESCRIPTION +.B vcmailbox +is a low-level utility for sending mailbox messages to the VideoCore. See +.B [MAILBOX] +or +.BR vcmailbox (7) +for more information on the available messages and their respective formats. +and +.BR raspiotp (7) +for some examples of typical usage. +. +. +.SH SEE ALSO +.BR vcgencmd (1), +.BR raspiotp (7), +.B [MAILBOX] +. +. +.SH REFERENCES +.TP +.B [MAILBOX] +https://github.com/raspberrypi/firmware/wiki/Mailbox-property-interface diff --git a/host_applications/linux/apps/vcmailbox/vcmailbox.7 b/host_applications/linux/apps/vcmailbox/vcmailbox.7 new file mode 100644 index 000000000..18ab2ace9 --- /dev/null +++ b/host_applications/linux/apps/vcmailbox/vcmailbox.7 @@ -0,0 +1,2237 @@ +.TH VCMAILBOX 7 +. +.SH NAME +vcmailbox \- the VideoCore mailbox property interface +. +. +.SH DESCRIPTION +. +The mailbox can be used by the ARM on the Raspberry Pi to communicate with the +VideoCore processor. +From the command line, the +.BR vcmailbox (1) +can be used for this purpose. +The mailbox operates a simple request / response protocol: +. +.IP \(bu 3 +The response overwrites the request. +.RS +.IP \(bu 3 +The callee is not allowed to return a different buffer address, this allows the +caller to make independent asynchronous requests. +.RE +. +.IP \(bu +The buffer itself is 16-byte aligned as only the upper 28 bits of the address +can be passed via the mailbox. +. +.IP \(bu +All u64/u32/u16 values are in host CPU endian order. +. +.IP \(bu +Unknown tags are ignored (the response bit will not be set). +. +.IP \(bu +Response may include unsolicited tags. +. +.IP \(bu +Response tag lengths may be longer than expected if additional information is +provided in a future format. +.RS +.IP \(bu 3 +The response is truncated to the provided buffer length. +.IP \(bu +Incompatible changes require a new tag so that where the buffer is the size +required by a previous version the truncated part should be readable as per the +previous version. +.IP \(bu +Response length indicates the desired length even when it is longer than the +buffer size filled. +.IP \(bu +Tag value length can be used to infer the version of the request/response. +.RE +. +.IP \(bu +Tags should be processed in order except where an interface requires multiple +tags for a single operation (like the frame buffer). +. +. +.SS Mailbox messages +. +.IP \(bu 3 +The mailbox interface has 28 bits (MSB) available for the value and 4 bits +(LSB) for the channel. +.RS +.IP \(bu 3 +Request message: 28 bits (MSB) buffer address +.IP \(bu +Response message: 28 bits (MSB) buffer address +.RE +. +.IP \(bu +Channels 8 and 9 are used. +.RS +.IP \(bu 3 +Channel 8: Request from ARM for response by VC +.IP \(bu +Channel 9: Request from VC for response by ARM (none currently defined) +.RE +. +. +.SS Buffer contents +. +. +.TP +.B u32 +buffer size in bytes (including the header values, the end tag and +padding) +. +.TP +.B u32 +buffer request/response code +.RS +.PP +Request codes: +.PD 0 +.TP 12 +.B 0x00000000 +process request +.TP +.B \& +All other values reserved +.PD +.PP +Response codes: +.PD 0 +.TP 12 +.B 0x80000000 +request successful +.TP +.B 0x80000001 +error parsing request buffer (partial response) +.TP +.B \& +All other values reserved +.PD +.RE +. +.TP +.B u8\|.\|.\|. +sequence of concatenated tags +. +.TP +.B u32 +0x0 (end tag) +. +.TP +.B u8\|.\|.\|. +padding +. +. +.SS Tag format +. +.TP +.B u32 +tag identifier +. +.TP +.B u32 +value buffer size in bytes +. +.TP +.B u32 +Request codes: +.PD 0 +.RS +.TP 12 +.B b31 clear +request +.TP +.B b30-b0 +reserved +.RE +.PD +.IP +Response codes: +.PD 0 +.RS +.TP 12 +.B b31 set +response +.TP +.B b30-b0 +value length in bytes +.RE +.PD +. +.TP +.B u8\|.\|.\|. +value buffer +. +.TP +.B u8\|.\|.\|. +padding to align the tag to 32 bits. +. +. +.SH VIDEOCORE TAGS +. +. +.SS Get firmware revision +.PD 0 +.TP 12 +.B Tag: +0x00000001 +.TP +.B Request: +0 bytes +.TP +.B Response: +4 bytes +.RS +.TP +.B u32 +firmware revision +.RE +.PD +. +. +.SH HARDWARE TAGS +. +.SS Get board model +.PD 0 +.TP 12 +.B Tag: +0x00010001 +.TP +.B Request: +0 bytes +.TP +.B Response: +4 bytes +.RS +.TP +.B u32 +board model +.RE +.PD +. +.SS Get board revision +.PD 0 +.TP 12 +.B Tag: +0x00010002 +.TP +.B Request: +0 bytes +.TP +.B Response: +4 bytes +.RS +.TP +.B u32 +board revision +.RE +.PD +. +.SS Get board MAC address +.PD 0 +.TP 12 +.B Tag: +0x00010003 +.TP +.B Request: +0 bytes +.TP +.B Response: +6 bytes +.RS +.TP +.B u8... +MAC address in network byte order +.RE +.PD +. +.SS Get board serial +.PD 0 +.TP 12 +.B Tag: +0x00010004 +.TP +.B Request: +0 bytes +.TP +.B Response: +8 bytes +.RS +.TP +.B u64 +board serial +.RE +.PD +. +.SS Get ARM memory +.PD 0 +.TP 12 +.B Tag: +0x00010005 +.TP +.B Request: +0 bytes +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +base address in bytes +.TP +.B u32 +size in bytes +.RE +.PD +. +.PP +Future formats may specify multiple base+size combinations. +. +.SS Get VC memory +.PD 0 +.TP 12 +.B Tag: +0x00010006 +.TP +.B Request: +0 bytes +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +base address in bytes +.TP +.B u32 +size in bytes +.RE +.PD +. +.PP +Future formats may specify multiple base+size combinations. +. +.SS Get clocks +.PD 0 +.TP 12 +.B Tag: +0x00010007 +.TP +.B Request: +0 bytes +.TP +.B Response: +variable bytes (multiple of 8) +.RS +.TP +.B u32 +parent clock id (0 for a root clock) +.TP +.B u32 +clock id +.TP +.B (repeated) +.RE +.PD +. +.PP +Returns all clocks that exist +.IR "in top-down, breadth-first order" . +Clocks that depend on another clock should be defined as children of that clock. Clocks that depend on no other clocks should have no parent. Clock IDs are as in the +.B CLOCK TAGS +section below. +. +. +.SH CONFIG TAGS +. +.SS Get command line +.PD 0 +.TP 12 +.B Tag: +0x00050001 +.TP +.B Request: +0 bytes +.TP +.B Response: +variable bytes +.RS +.TP +.B u8... +ASCII command line string +.RE +.PD +. +.PP +Caller should not assume the string is null terminated. +. +. +.SH SHARED RESOURCE MANAGEMENT TAGS +. +.SS Get DMA channels +.PD 0 +.TP 12 +.B Tag: +0x00060001 +.TP +.B Request: +0 bytes +.TP +.B Response: +4 bytes +.RS +.TP +.B u32 +mask +.RS +.TP 12 +.B Bits 0-15 +DMA channels 0-15 (0=do not use, 1=usable) +.TP +.B Bits 16-31 +reserved for future use +.RE +.RE +.PD +. +.PP +Caller assumes that the VC has enabled all the usable DMA channels. +. +. +.SH POWER TAGS +. +.SS Unique device IDs +.PD 0 +.TP 12 +.B 0x00000000 +SD Card +.TP +.B 0x00000001 +UART0 +.TP +.B 0x00000002 +UART1 +.TP +.B 0x00000003 +USB HCD +.TP +.B 0x00000004 +I2C0 +.TP +.B 0x00000005 +I2C1 +.TP +.B 0x00000006 +I2C2 +.TP +.B 0x00000007 +SPI +.TP +.B 0x00000008 +CCP2TX +.TP +.B 0x00000009 +Unknown (RPi4) +.TP +.B 0x0000000a +Unknown (RPi4) +.PD +. +.SS Get power state +.PD 0 +.TP 12 +.B Tag: +0x00020001 +.TP +.B Request: +4 bytes +.RS +.TP +.B u32 +device id +.RE +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +device id +.TP +.B u32 +state +.RS +.TP 12 +.B Bit 0 +0=off, 1=on +.TP +.B Bit 1 +0=device exists, 1=device does not exist +.TP +.B Bits 2-31 +reserved for future use +.RE +.RE +.PD +. +.PP +Response indicates current state. +. +.SS Get timing +.PD 0 +.TP 12 +.B Tag: +0x00020002 +.TP +.B Request: +4 bytes +.RS +.TP +.B u32 +device id +.RE +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +device id +.TP +.B u32 +enable wait time in microseconds +.RE +.PD +. +.PP +Response indicates wait time required after turning a device on before power is stable. Returns 0 wait time if the device does not exist. +. +.SS Set power state +.PD 0 +.TP 12 +.B Tag: +0x00028001 +.TP +.B Request: +8 bytes +.RS +.TP +.B u32 +device id +.TP +.B u32 +state +.RS +.TP 12 +.B Bit 0 +0=off, 1=on +.TP +.B Bit 1 +0=do not wait, 1=wait +.TP +.B Bits 2-31 +reserved for future use (set to 0) +.RE +.RE +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +device id +.TP +.B u32 +state +.RS +.TP 12 +.B Bit 0 +0=off, 1=on +.TP +.B Bit 1 +0=device exists, 1=device does not exist +.TP +.B Bits 2-31 +reserved for future use +.RE +.RE +.PD +. +.PP +Response indicates new state, with/without waiting for the power to become stable. +. +. +.SH CLOCK TAGS +. +.SS Unique clock IDs +.PD 0 +.TP 12 +.B 0x00000000 +reserved +.TP +.B 0x00000001 +EMMC +.TP +.B 0x00000002 +UART +.TP +.B 0x00000003 +ARM +.TP +.B 0x00000004 +CORE +.TP +.B 0x00000005 +V3D +.TP +.B 0x00000006 +H264 +.TP +.B 0x00000007 +ISP +.TP +.B 0x00000008 +SDRAM +.TP +.B 0x00000009 +PIXEL +.TP +.B 0x0000000a +PWM +.TP +.B 0x0000000b +HEVC +.TP +.B 0x0000000c +EMMC2 +.TP +.B 0x0000000d +M2MC +.TP +.B 0x0000000e +PIXEL_BVB +.PD +. +.PP +All clocks are the +.I base clocks +for those peripherals, e.g. 3MHz for UART, 50/100MHz for EMMC, not the dividers applied using the peripheral. +. +.SS Get clock state +.PD 0 +.TP 12 +.B Tag: +0x00030001 +.TP +.B Request: +4 bytes +.RS +.TP +.B u32 +clock id +.RE +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +clock id +.TP +.B u32 +state +.RS +.TP 12 +.B Bit 0 +0=off, 1=on +.TP +.B Bit 1 +0=clock exists, 1=clock does not exist +.TP +.B Bits 2-31 +reserved for future use +.RE +.RE +.PD +. +.SS Set clock state +.PD 0 +.TP 12 +.B Tag: +0x00038001 +.TP +.B Request: +8 bytes +.RS +.TP +.B u32 +clock id +.TP +.B u32 +state +.RS +.TP 12 +.B Bit 0 +0=off, 1=on +.TP +.B Bit 1 +0=clock exists, 1=clock does not exist +.TP +.B Bits 2-31 +reserved for future use (set to 0) +.RE +.RE +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +clock id +.TP +.B u32 +state +.RS +.TP 12 +.B Bit 0 +0=off, 1=on +.TP +.B Bit 1 +0=clock exists, 1=clock does not exist +.TP +.B Bits 2-31 +reserved for future use +.RE +.RE +.PD +. +.SS Get clock rate +.PD 0 +.TP 12 +.B Tag: +0x00030002 +.TP +.B Request: +4 bytes +.RS +.TP +.B u32 +clock id +.RE +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +clock id +.TP +.B u32 +rate (in Hz) +.RE +.PD +. +.PP +Next enable rate should be returned even if the clock is not running. A rate of 0 is returned if the clock does not exist. +. +.SS Set clock rate +.PD 0 +.TP 12 +.B Tag: +0x00038002 +.TP +.B Request: +12 bytes +.RS +.TP +.B u32 +clock id +.TP +.B u32 +rate (in Hz) +.TP +.B u32 +skip setting turbo +.RE +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +clock id +.TP +.B u32 +rate (in Hz) +.RE +.PD +. +.PP +Next supported enable rate should be returned even if the clock is not running. A rate of 0 is returned if the clock does not exist. The clock rate may be clamped to the supported range. +. +.PP +By default when setting arm freq above default, other turbo settings will be enabled (e.g. voltage, sdram and gpu frequencies). You can disable this effect by setting "skip setting turbo" to 1. +. +.SS Get max clock rate +.PD 0 +.TP 12 +.B Tag: +0x00030004 +.TP +.B Request: +4 bytes +.RS +.TP +.B u32 +clock id +.RE +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +clock id +.TP +.B u32 +rate (in Hz) +.RE +.PD +. +.PP +Return the maximum supported clock rate for the given clock. Clocks should not be set higher than this. +. +.SS Get min clock rate +.PD 0 +.TP 12 +.B Tag: +0x00030007 +.TP +.B Request: +4 bytes +.RS +.TP +.B u32 +clock id +.RE +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +clock id +.TP +.B u32 +rate (in Hz) +.RE +.PD +. +.PP +Return the minimum supported clock rate for the given clock. This may be used when idle. +. +.SS Get turbo +.PD 0 +.TP 12 +.B Tag: +0x00030009 +.TP +.B Request: +4 bytes +.RS +.TP +.B u32 +id +.RE +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +id +.TP +.B u32 +level +.RE +.PD +. +.PP +Get the turbo state for index id. id should be 0. level will be zero for non-turbo and one for turbo. +. +.SS Set turbo +.PD 0 +.TP 12 +.B Tag: +0x00038009 +.TP +.B Request: +8 bytes +.RS +.TP +.B u32 +id +.TP +.B u32 +level +.RE +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +id +.TP +.B u32 +level +.RE +.PD +. +.PP +Set the turbo state for index id. id should be zero. level will be zero for non-turbo and one for turbo. +This will cause GPU clocks to be set to maximum when enabled and minimum when disabled. +. +. +.SH VOLTAGE TAGS +. +.SS Unique voltage IDs +.PD 0 +.TP 12 +.B 0x00000000 +reserved +.TP +.B 0x00000001 +Core +.TP +.B 0x00000002 +SDRAM_C +.TP +.B 0x00000003 +SDRAM_P +.TP +.B 0x00000004 +SDRAM_I +.PD +. +.SS Get voltage +.PD 0 +.TP 12 +.B Tag: +0x00030003 +.TP +.B Request: +4 bytes +.RS +.TP +.B u32 +voltage id +.RE +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +voltage id +.TP +.B u32 +value (offset from 1.2V in units of 0.025V) +.RE +.PD +. +.PP +The voltage value may be clamped to the supported range. +A value of 0x80000000 means the id was not valid. +. +.SS Set voltage +.PD 0 +.TP 12 +.B Tag: +0x00038003 +.TP +.B Request: +8 bytes +.RS +.TP +.B u32 +voltage id +.TP +.B u32 +value (offset from 1.2V in units of 0.025V) +.RE +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +voltage id +.TP +.B u32 +value (offset from 1.2V in units of 0.025V) +.RE +.PD +. +.PP +The voltage value may be clamped to the supported range. +A value of 0x80000000 means the id was not valid. +. +.SS Get max voltage +.PD 0 +.TP 12 +.B Tag: +0x00030005 +.TP +.B Request: +4 bytes +.RS +.TP +.B u32 +voltage id +.RE +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +voltage id +.TP +.B u32 +value (offset from 1.2V in units of 0.025V) +.RE +.PD +. +.PP +Return the maximum supported voltage rate for the given id. Voltages should not be set higher than this. +. +.SS Get min voltage +.PD 0 +.TP 12 +.B Tag: +0x00030008 +.TP +.B Request: +4 bytes +.RS +.TP +.B u32 +voltage id +.RE +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +voltage id +.TP +.B u32 +value (offset from 1.2V in units of 0.025V) +.RE +.PD +. +.PP +Return the minimum supported voltage rate for the given id. This may be used when idle. +. +.SS Get temperature +.PD 0 +.TP 12 +.B Tag: +0x00030006 +.TP +.B Request: +4 bytes +.RS +.TP +.B u32 +temperature id +.RE +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +temperature id +.TP +.B u32 +value +.RE +.PD +. +.PP +Return the temperature of the SoC in thousandths of a degree C. id should be zero. +. +.SS Get max temperature +.PD 0 +.TP 12 +.B Tag: +0x0003000a +.TP +.B Request: +4 bytes +.RS +.TP +.B u32 +temperature id +.RE +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +temperature id +.TP +.B u32 +value +.RE +.PD +. +.PP +Return the maximum safe temperature of the SoC in thousandths of a degree C. id should be zero. +Overclock may be disabled above this temperature. +. +.SS Allocate memory +.PD 0 +.TP 12 +.B Tag: +0x0003000c +.TP +.B Request: +12 bytes +.RS +.TP +.B u32 +size +.TP +.B u32 +alignment +.TP +.B u32 +flags +.RE +.TP +.B Response: +4 bytes +.RS +.TP +.B u32 +handle +.RE +.PD +. +.PP +Allocates contiguous memory on the GPU. size and alignment are in bytes. flags contain: +. +.PP +.TS +l l l . +Name Value Comments +\_ \_ \_ +MEM_FLAG_NORMAL 0 normal allocating alias; don't use from ARM +MEM_FLAG_DISCARDABLE 1 << 0 can be resized to 0 at any time; use for cached data +MEM_FLAG_DIRECT 1 << 2 0xC alias uncached +MEM_FLAG_COHERENT 1 << 3 0x8 alias; non-allocating in L2 but coherent +MEM_FLAG_L1_NONALLOCATING 3 << 2 Allocating in L2 +MEM_FLAG_ZERO 1 << 4 Initialise buffer to all zeros +MEM_FLAG_NO_INIT 1 << 5 Don't initialise; default is initialise to all ones +MEM_FLAG_HINT_PERMALOCK 1 << 6 Likely to be locked for long periods of time +.TE +. +.SS Lock memory +.PD 0 +.TP 12 +.B Tag: +0x0003000d +.TP +.B Request: +4 bytes +.RS +.TP +.B u32 +handle +.RE +.TP +.B Response: +4 bytes +.RS +.TP +.B u32 +bus address +.RE +.PD +. +.PP +Lock buffer in place, and return a bus address. Must be done before memory can be accessed +. +.SS Unlock memory +.PD 0 +.TP 12 +.B Tag: +0x0003000e +.TP +.B Request: +4 bytes +.RS +.TP +.B u32 +handle +.RE +.TP +.B Response: +4 bytes +.RS +.TP +.B u32 +status +.RE +.PD +. +.PP +Unlock buffer. It retains contents, but may move. Needs to be locked before next use. +status=0 is success. +. +.SS Release Memory +.PD 0 +.TP 12 +.B Tag: +0x0003000f +.TP +.B Request: +4 bytes +.RS +.TP +.B u32 +handle +.RE +.TP +.B Response: +4 bytes +.RS +.TP +.B u32 +status +.RE +.PD +. +.PP +Free the memory buffer. status=0 is success. +. +.SS Execute Code +.PD 0 +.TP 12 +.B Tag: +0x00030010 +.TP +.B Request: +28 bytes +.RS +.TP +.B u32 +function pointer +.TP +.B u32 +r0 +.TP +.B u32 +r1 +.TP +.B u32 +r2 +.TP +.B u32 +r3 +.TP +.B u32 +r4 +.TP +.B u32 +r5 +.RE +.TP +.B Response: +4 bytes +.RS +.TP +.B u32 +r0 +.RE +.PD +. +.PP +Calls the function at given (bus) address and with arguments given. E.g. +r0 = fn(r0, r1, r2, r3, r4, r5); +It blocks until call completes. The (GPU) instruction cache is implicitly flushed. +Setting the lsb of function pointer address will suppress the instruction cache flush if you know the buffer hasn't changed since last execution. +. +.SS Get Dispmanx Resource mem handle +.PD 0 +.TP 12 +.B Tag: +0x00030014 +.TP +.B Request: +4 bytes +.RS +.TP +.B u32 +dispmanx resource handle +.RE +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +0 is successful +.TP +.B u32 +mem handle for resource +.RE +.PD +. +.PP +Gets the mem_handle associated with a created dispmanx resource. +This can be locked and the memory directly written from the arm to avoid having to copy the image data to GPU. +. +.SS Get EDID block +.PD 0 +.TP 12 +.B Tag: +0x00030020 +.TP +.B Request: +4 bytes +.RS +.TP +.B u32 +block number +.RE +.TP +.B Response: +136 bytes +.RS +.TP +.B u32 +block number +.TP +.B u32 +status +.TP +.B u8\|.\|.\|. +EDID block +.RE +.PD +. +.PP +This reads the specified EDID block from attached HDMI/DVI device. +There will always be at least one block of 128 bytes, but there may be additional blocks. You should keep requesting blocks (starting from 0) until the status returned is non-zero. +. +. +.SH FRAME BUFFER TAGS +. +.IP \(bu 3 +All tags in the request are processed in one operation. +.IP \(bu +It is not valid to mix Test tags with Get/Set tags in the same operation and no tags will be returned. +.IP \(bu +Get tags will be processed after all Set tags. +.IP \(bu +If an allocate buffer tag is omitted when setting parameters, then no change occurs unless it can be accommodated without changing the buffer base or size. +.IP \(bu +When an allocate buffer response is returned, the old buffer area (if the base or size has changed) is implicitly freed. +. +.PP +For example: +. +.IP 1. 3 +The current values/defaults are loaded into a temporary struct +. +.IP 2. +The tags are used to overwrite some or all of the values +. +.IP 3. +Validation of Test/Set tags occurs +. +.IP 4. +The Set changes are applied and responses based on the requested Get/Test/Set tags are written to the buffer +. +Duplicating the same tag in one request/response is prohibited. The expected result is either an error or implementation specified undefined behaviour (such as only using the last instance of the tag). +.PD +. +.SS Allocate buffer +.PD 0 +.TP 12 +.B Tag: +0x00040001 +.TP +.B Request: +4 bytes +.RS +.TP +.B u32 +alignment in bytes +.RE +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +frame buffer base address in bytes +.TP +.B u32 +frame buffer size in bytes +.RE +.PD +. +.PP +If the requested alignment is unsupported then the current base and size (which may be 0 if not allocated) is returned and no change occurs. +. +.SS Release buffer +.PD 0 +.TP 12 +.B Tag: +0x00048001 +.TP +.B Request: +0 bytes +.TP +.B Response: +0 bytes +.PD +. +.PP +Releases and disables the frame buffer. +. +.SS Blank screen +.PD 0 +.TP 12 +.B Tag: +0x00040002 +.TP +.B Request: +4 bytes +.RS +.TP +.B u32 +state +.RS +.TP 12 +.B Bit 0 +0=off, 1=on +.TP +.B Bits 1-31 +reserved for future use (set to 0) +.RE +.RE +.TP +.B Response: +4 bytes +.RS +.TP +.B u32 +state +.RS +.TP 12 +.B Bit 0 +0=off, 1=on +.TP +.B Bits 1-31 +reserved for future use +.RE +.RE +.PD +. +.SS Get physical (display) width/height +.PD 0 +.TP 12 +.B Tag: +0x00040003 +.TP +.B Request: +0 bytes +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +width in pixels +.TP +.B u32 +height in pixels +.RE +.PD +. +.PP +Note that the "physical (display)" size is the size of the allocated buffer in memory, not the resolution of the video signal sent to the display device. +. +.SS Test physical (display) width/height +.PD 0 +.TP 12 +.B Tag: +0x00044003 +.TP +.B Request: +8 bytes +.RS +.TP +.B u32 +width in pixels +.TP +.B u32 +height in pixels +.RE +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +width in pixels +.TP +.B u32 +height in pixels +.RE +.PD +. +.PP +Response is the same as the request (or modified), to indicate if this configuration is supported (in combination with all the other settings). Does not modify the current hardware or frame buffer state. +. +.SS Set physical (display) width/height +.PD 0 +.TP 12 +.B Tag: +0x00048003 +.TP +.B Request: +8 bytes +.RS +.TP +.B u32 +width in pixels +.TP +.B u32 +height in pixels +.RE +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +width in pixels +.TP +.B u32 +height in pixels +.RE +.PD +. +.PP +The response may not be the same as the request so it must be checked. May be the previous width/height or 0 for unsupported. +. +. +.SS Get virtual (buffer) width/height +.PD 0 +.TP 12 +.B Tag: +0x00040004 +.TP +.B Request: +0 bytes +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +width in pixels +.TP +.B u32 +height in pixels +.RE +.PD +. +.PP +Note that the "virtual (buffer)" size is the portion of buffer that is sent to the display device, not the resolution the buffer itself. This may be smaller than the allocated buffer size in order to implement panning. +. +.SS Test virtual (buffer) width/height +.PD 0 +.TP 12 +.B Tag: +0x00044004 +.TP +.B Request: +8 bytes +.RS +.TP +.B u32 +width in pixels +.TP +.B u32 +height in pixels +.RE +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +width in pixels +.TP +.B u32 +height in pixels +.RE +.PD +. +.PP +Response is the same as the request (or modified), to indicate if this configuration is supported (in combination with all the other settings). Does not modify the current hardware or frame buffer state. +. +.SS Set virtual (buffer) width/height +.PD 0 +.TP 12 +.B Tag: +0x00048004 +.TP +.B Request: +8 bytes +.RS +.TP +.B u32 +width in pixels +.TP +.B u32 +height in pixels +.RE +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +width in pixels +.TP +.B u32 +height in pixels +.RE +.PD +. +.PP +The response may not be the same as the request so it must be checked. May be the previous width/height or 0 for unsupported. +. +.SS Get depth +.PD 0 +.TP 12 +.B Tag: +0x00040005 +.TP +.B Request: +0 bytes +.TP +.B Response: +4 bytes +.RS +.TP +.B u32 +bits per pixel +.RE +.PD +. +.PP +Test depth +.PD 0 +.TP 12 +.B Tag: +0x00044005 +.TP +.B Request: +4 bytes +.RS +.TP +.B u32 +bits per pixel +.RE +.TP +.B Response: +4 bytes +.RS +.TP +.B u32 +bits per pixel +.RE +.PD +. +.PP +Response is the same as the request (or modified), to indicate if this configuration is supported (in combination with all the other settings). Does not modify the current hardware or frame buffer state. +. +.SS Set depth +.PD 0 +.TP 12 +.B Tag: +0x00048005 +.TP +.B Request: +4 bytes +.RS +.TP +.B u32 +bits per pixel +.RE +.TP +.B Response: +4 bytes +.RS +.TP +.B u32 +bits per pixel +.RE +.PD +. +.PP +The response may not be the same as the request so it must be checked. May be the previous depth or 0 for unsupported. +. +.SS Get pixel order +.PD 0 +.TP 12 +.B Tag: +0x00040006 +.TP +.B Request: +0 bytes +.TP +.B Response: +4 bytes +.RS +.TP +.B u32 +state +.RS +.TP +.B 0x0 +BGR +.TP +.B 0x1 +RGB +.RE +.RE +.PD +. +.SS Test pixel order +.PD 0 +.TP 12 +.B Tag: +0x00044006 +.TP +.B Request: +4 bytes +.RS +.TP +.B u32 +state (as above) +.RE +.TP +.B Response: +4 bytes +.RS +.TP +.B u32 +state (as above) +.RE +.PD +. +.PP +Response is the same as the request (or modified), to indicate if this configuration is supported (in combination with all the other settings). Does not modify the current hardware or frame buffer state. +. +.SS Set pixel order +.PD 0 +.TP 12 +.B Tag: +0x00048006 +.TP +.B Request: +4 bytes +.RS +.TP +.B u32 +state (as above) +.RE +.TP +.B Response: +4 bytes +.RS +.TP +.B u32 +state (as above) +.RE +.PD +. +.PP +The response may not be the same as the request so it must be checked. +. +.SS Get alpha mode +.PD 0 +.TP 12 +.B Tag: +0x00040007 +.TP +.B Request: +0 bytes +.TP +.B Response: +4 bytes +.RS +.TP +.B u32 +state +.RS +.TP +.B 0x0 +Alpha channel enabled (0 = fully opaque) +.TP +.B 0x1 +Alpha channel reversed (0 = fully transparent) +.TP +.B 0x2 +Alpha channel ignored +.RE +.RE +.PD +. +.SS Test alpha mode +.PD 0 +.TP 12 +.B Tag: +0x00044007 +.TP +.B Request: +4 bytes +.RS +.TP +.B u32 +state (as above) +.RE +.TP +.B Response: +4 bytes +.RS +.TP +.B u32 +state (as above) +.RE +.PD +. +.PP +Response is the same as the request (or modified), to indicate if this configuration is supported (in combination with all the other settings). Does not modify the current hardware or frame buffer state. +. +.SS Set alpha mode +.PD 0 +.TP 12 +.B Tag: +0x00048007 +.TP +.B Request: +4 bytes +.RS +.TP +.B u32 +state (as above) +.RE +.TP +.B Response: +4 bytes +.RS +.TP +.B u32 +state (as above) +.RE +.PD +. +.PP +The response may not be the same as the request so it must be checked. +. +.SS Get pitch +.PD 0 +.TP 12 +.B Tag: +0x00040008 +.TP +.B Request: +0 bytes +.TP +.B Response: +4 bytes +.RS +.TP +.B u32 +bytes per line +.RE +.PD +. +.SS Get virtual offset +.PD 0 +.TP 12 +.B Tag: +0x00040009 +.TP +.B Request: +0 bytes +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +X in pixels +.TP +.B u32 +Y in pixels +.RE +.PD +. +.SS Test virtual offset +.PD 0 +.TP 12 +.B Tag: +0x00044009 +.TP +.B Request: +8 bytes +.RS +.TP +.B u32 +X in pixels +.TP +.B u32 +Y in pixels +.RE +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +X in pixels +.TP +.B u32 +Y in pixels +.RE +.PD +. +.PP +Response is the same as the request (or modified), to indicate if this configuration is supported (in combination with all the other settings). Does not modify the current hardware or frame buffer state. +. +.SS Set virtual offset +.PD 0 +.TP 12 +.B Tag: +0x00048009 +.TP +.B Request: +8 bytes +.RS +.TP +.B u32 +X in pixels +.TP +.B u32 +Y in pixels +.RE +.TP +.B Response: +8 bytes +.RS +.TP +.B u32 +X in pixels +.TP +.B u32 +Y in pixels +.RE +.PD +. +.PP +The response may not be the same as the request so it must be checked. May be the previous offset or 0 for unsupported. +. +.SS Get overscan +.PD 0 +.TP 12 +.B Tag: +0x0004000a +.TP +.B Request: +0 bytes +.TP +.B Response: +16 bytes +.RS +.TP +.B u32 +top in pixels +.TP +.B u32 +bottom in pixels +.TP +.B u32 +left in pixels +.TP +.B u32 +right in pixels +.RE +.PD +. +.SS Test overscan +.PD 0 +.TP 12 +.B Tag: +0x0004400a +.TP +.B Request: +16 bytes +.RS +.TP +.B u32 +top in pixels +.TP +.B u32 +bottom in pixels +.TP +.B u32 +left in pixels +.TP +.B u32 +right in pixels +.RE +.TP +.B Response: +16 bytes +.RS +.TP +.B u32 +top in pixels +.TP +.B u32 +bottom in pixels +.TP +.B u32 +left in pixels +.TP +.B u32 +right in pixels +.RE +.PD +. +.PP +Response is the same as the request (or modified), to indicate if this configuration is supported (in combination with all the other settings). Does not modify the current hardware or frame buffer state. +. +.SS Set overscan +.PD 0 +.TP 12 +.B Tag: +0x0004800a +.TP +.B Request: +16 bytes +.RS +.TP +.B u32 +top in pixels +.TP +.B u32 +bottom in pixels +.TP +.B u32 +left in pixels +.TP +.B u32 +right in pixels +.RE +.TP +.B Response: +16 bytes +.RS +.TP +.B u32 +top in pixels +.TP +.B u32 +bottom in pixels +.TP +.B u32 +left in pixels +.TP +.B u32 +right in pixels +.RE +.PD +. +.PP +The response may not be the same as the request so it must be checked. May be the previous overscan or 0 for unsupported. +. +.SS Get palette +.PD 0 +.TP 12 +.B Tag: +0x0004000b +.TP +.B Request: +0 bytes +.TP +.B Response: +1024 bytes +.RS +.TP +.B u32... +RGBA palette values (index 0 to 255) +.RE +.PD +. +.SS Test palette +.PD 0 +.TP 12 +.B Tag: +0x0004400b +.TP +.B Request: +24 bytes..1032 bytes +.RS +.TP +.B u32 +offset: first palette index to set (0-255) +.TP +.B u32 +length: number of palette entries to set (1-256) +.TP +.B u32... +RGBA palette values (offset to offset+length-1) +.RE +.TP +.B Response: +4 bytes +.RS +.TP +.B u32 +0=valid, 1=invalid +.RE +.PD +. +.PP +Response is the same as the request (or modified), to indicate if this configuration is supported (in combination with all the other settings). Does not modify the current hardware or frame buffer state. +. +.SS Set palette +.PD 0 +.TP 12 +.B Tag: +0x0004800b +.TP +.B Request: +24 bytes..1032 bytes +.RS +.TP +.B u32 +offset: first palette index to set (0-255) +.TP +.B u32 +length: number of palette entries to set (1-256) +.TP +.B u32... +RGBA palette values (offset to offset+length-1) +.RE +.TP +.B Response: +4 bytes +.RS +.TP +.B u32 +0=valid, 1=invalid +.RE +.PD +. +.PP +The response may not be the same as the request so it must be checked. Palette changes should not be partially applied. +. +.SS Set Cursor Info +.PD 0 +.TP 12 +.B Tag: +0x00008010 +.TP +.B Request: +24 bytes +.RS +.TP +.B u32 +width +.TP +.B u32 +height +.TP +.B u32 +(unused) +.TP +.B u32 +pointer to pixels +.TP +.B u32 +hotspotX +.TP +.B u32 +hotspotY +.RE +.TP +.B Response: +4 bytes +.RS +.TP +.B u32 +0=valid, 1=invalid +.RE +.PD +. +.PP +Format is 32bpp (ARGB). +Width and height should be >= 16 and (width * height) <= 64. +. +.SS Set Cursor State +.PD 0 +.TP 12 +.B Tag: +0x00008011 +.TP +.B Request: +16 bytes +.RS +.TP +.B u32 +enable (1=visible, 0=invisible) +.TP +.B u32 +x +.TP +.B u32 +y +.TP +.B u32 +flags; 0=display coords, 1=framebuffer coords +.RE +.TP +.B Response: +4 bytes +.RS +.TP +.B u32 +0=valid, 1=invalid +.RE +.PD +. +.PP +if Set Cursor Info hasn't been called a default cursor will be used (64x64 with hotspot at 0,0).