diff options
Diffstat (limited to 'Documentation/driver-api')
63 files changed, 10860 insertions, 90 deletions
diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driver-api/dma-buf.rst index c78db28519f7..63dec76d1d8d 100644 --- a/Documentation/driver-api/dma-buf.rst +++ b/Documentation/driver-api/dma-buf.rst @@ -11,7 +11,7 @@ course not limited to GPU use cases. The three main components of this are: (1) dma-buf, representing a sg_table and exposed to userspace as a file descriptor to allow passing between devices, (2) fence, which provides a mechanism to signal when -one device as finished access, and (3) reservation, which manages the +one device has finished access, and (3) reservation, which manages the shared or exclusive fence(s) associated with the buffer. Shared DMA Buffers @@ -31,7 +31,7 @@ The exporter - implements and manages operations in :c:type:`struct dma_buf_ops <dma_buf_ops>` for the buffer, - allows other users to share the buffer by using dma_buf sharing APIs, - - manages the details of buffer allocation, wrapped int a :c:type:`struct + - manages the details of buffer allocation, wrapped in a :c:type:`struct dma_buf <dma_buf>`, - decides about the actual backing storage where this allocation happens, - and takes care of any migration of scatterlist - for all (shared) users of diff --git a/Documentation/driver-api/driver-model/device.rst b/Documentation/driver-api/driver-model/device.rst index 2b868d49d349..b9b022371e85 100644 --- a/Documentation/driver-api/driver-model/device.rst +++ b/Documentation/driver-api/driver-model/device.rst @@ -50,10 +50,10 @@ Attributes Attributes of devices can be exported by a device driver through sysfs. -Please see Documentation/filesystems/sysfs.txt for more information +Please see Documentation/filesystems/sysfs.rst for more information on how sysfs works. -As explained in Documentation/kobject.txt, device attributes must be +As explained in Documentation/core-api/kobject.rst, device attributes must be created before the KOBJ_ADD uevent is generated. The only way to realize that is by defining an attribute group. diff --git a/Documentation/driver-api/driver-model/devres.rst b/Documentation/driver-api/driver-model/devres.rst index 46c13780994c..fc242ed4bde5 100644 --- a/Documentation/driver-api/driver-model/devres.rst +++ b/Documentation/driver-api/driver-model/devres.rst @@ -372,6 +372,11 @@ MUX devm_mux_chip_register() devm_mux_control_get() +NET + devm_alloc_etherdev() + devm_alloc_etherdev_mqs() + devm_register_netdev() + PER-CPU MEM devm_alloc_percpu() devm_free_percpu() diff --git a/Documentation/driver-api/driver-model/overview.rst b/Documentation/driver-api/driver-model/overview.rst index d4d1e9b40e0c..e98d0ab4a9b6 100644 --- a/Documentation/driver-api/driver-model/overview.rst +++ b/Documentation/driver-api/driver-model/overview.rst @@ -121,4 +121,4 @@ device-specific data or tunable interfaces. More information about the sysfs directory layout can be found in the other documents in this directory and in the file -Documentation/filesystems/sysfs.txt. +Documentation/filesystems/sysfs.rst. diff --git a/Documentation/driver-api/gpio/board.rst b/Documentation/driver-api/gpio/board.rst index ce91518bf9f4..191fa867826a 100644 --- a/Documentation/driver-api/gpio/board.rst +++ b/Documentation/driver-api/gpio/board.rst @@ -113,13 +113,15 @@ files that desire to do so need to include the following header:: GPIOs are mapped by the means of tables of lookups, containing instances of the gpiod_lookup structure. Two macros are defined to help declaring such mappings:: - GPIO_LOOKUP(chip_label, chip_hwnum, con_id, flags) - GPIO_LOOKUP_IDX(chip_label, chip_hwnum, con_id, idx, flags) + GPIO_LOOKUP(key, chip_hwnum, con_id, flags) + GPIO_LOOKUP_IDX(key, chip_hwnum, con_id, idx, flags) where - - chip_label is the label of the gpiod_chip instance providing the GPIO - - chip_hwnum is the hardware number of the GPIO within the chip + - key is either the label of the gpiod_chip instance providing the GPIO, or + the GPIO line name + - chip_hwnum is the hardware number of the GPIO within the chip, or U16_MAX + to indicate that key is a GPIO line name - con_id is the name of the GPIO function from the device point of view. It can be NULL, in which case it will match any function. - idx is the index of the GPIO within the function. @@ -135,7 +137,10 @@ where In the future, these flags might be extended to support more properties. -Note that GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0. +Note that: + 1. GPIO line names are not guaranteed to be globally unique, so the first + match found will be used. + 2. GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0. A lookup table can then be defined as follows, with an empty entry defining its end. The 'dev_id' field of the table is the identifier of the device that will diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index d4e78cb3ef4d..6567187e7687 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -39,6 +39,7 @@ available subsections can be seen below. spi i2c ipmb + ipmi i3c/index interconnect devfreq @@ -63,6 +64,7 @@ available subsections can be seen below. pinctl gpio/index md/index + media/index misc_devices nfc/index dmaengine/index diff --git a/Documentation/driver-api/infiniband.rst b/Documentation/driver-api/infiniband.rst index 1a3116f32ff0..30e142ccbee9 100644 --- a/Documentation/driver-api/infiniband.rst +++ b/Documentation/driver-api/infiniband.rst @@ -37,9 +37,6 @@ InfiniBand core interfaces .. kernel-doc:: drivers/infiniband/core/ud_header.c :export: -.. kernel-doc:: drivers/infiniband/core/fmr_pool.c - :export: - .. kernel-doc:: drivers/infiniband/core/umem.c :export: diff --git a/Documentation/driver-api/ipmi.rst b/Documentation/driver-api/ipmi.rst new file mode 100644 index 000000000000..5ef1047e2e66 --- /dev/null +++ b/Documentation/driver-api/ipmi.rst @@ -0,0 +1,746 @@ +===================== +The Linux IPMI Driver +===================== + +:Author: Corey Minyard <minyard@mvista.com> / <minyard@acm.org> + +The Intelligent Platform Management Interface, or IPMI, is a +standard for controlling intelligent devices that monitor a system. +It provides for dynamic discovery of sensors in the system and the +ability to monitor the sensors and be informed when the sensor's +values change or go outside certain boundaries. It also has a +standardized database for field-replaceable units (FRUs) and a watchdog +timer. + +To use this, you need an interface to an IPMI controller in your +system (called a Baseboard Management Controller, or BMC) and +management software that can use the IPMI system. + +This document describes how to use the IPMI driver for Linux. If you +are not familiar with IPMI itself, see the web site at +http://www.intel.com/design/servers/ipmi/index.htm. IPMI is a big +subject and I can't cover it all here! + +Configuration +------------- + +The Linux IPMI driver is modular, which means you have to pick several +things to have it work right depending on your hardware. Most of +these are available in the 'Character Devices' menu then the IPMI +menu. + +No matter what, you must pick 'IPMI top-level message handler' to use +IPMI. What you do beyond that depends on your needs and hardware. + +The message handler does not provide any user-level interfaces. +Kernel code (like the watchdog) can still use it. If you need access +from userland, you need to select 'Device interface for IPMI' if you +want access through a device driver. + +The driver interface depends on your hardware. If your system +properly provides the SMBIOS info for IPMI, the driver will detect it +and just work. If you have a board with a standard interface (These +will generally be either "KCS", "SMIC", or "BT", consult your hardware +manual), choose the 'IPMI SI handler' option. A driver also exists +for direct I2C access to the IPMI management controller. Some boards +support this, but it is unknown if it will work on every board. For +this, choose 'IPMI SMBus handler', but be ready to try to do some +figuring to see if it will work on your system if the SMBIOS/APCI +information is wrong or not present. It is fairly safe to have both +these enabled and let the drivers auto-detect what is present. + +You should generally enable ACPI on your system, as systems with IPMI +can have ACPI tables describing them. + +If you have a standard interface and the board manufacturer has done +their job correctly, the IPMI controller should be automatically +detected (via ACPI or SMBIOS tables) and should just work. Sadly, +many boards do not have this information. The driver attempts +standard defaults, but they may not work. If you fall into this +situation, you need to read the section below named 'The SI Driver' or +"The SMBus Driver" on how to hand-configure your system. + +IPMI defines a standard watchdog timer. You can enable this with the +'IPMI Watchdog Timer' config option. If you compile the driver into +the kernel, then via a kernel command-line option you can have the +watchdog timer start as soon as it initializes. It also have a lot +of other options, see the 'Watchdog' section below for more details. +Note that you can also have the watchdog continue to run if it is +closed (by default it is disabled on close). Go into the 'Watchdog +Cards' menu, enable 'Watchdog Timer Support', and enable the option +'Disable watchdog shutdown on close'. + +IPMI systems can often be powered off using IPMI commands. Select +'IPMI Poweroff' to do this. The driver will auto-detect if the system +can be powered off by IPMI. It is safe to enable this even if your +system doesn't support this option. This works on ATCA systems, the +Radisys CPI1 card, and any IPMI system that supports standard chassis +management commands. + +If you want the driver to put an event into the event log on a panic, +enable the 'Generate a panic event to all BMCs on a panic' option. If +you want the whole panic string put into the event log using OEM +events, enable the 'Generate OEM events containing the panic string' +option. You can also enable these dynamically by setting the module +parameter named "panic_op" in the ipmi_msghandler module to "event" +or "string". Setting that parameter to "none" disables this function. + +Basic Design +------------ + +The Linux IPMI driver is designed to be very modular and flexible, you +only need to take the pieces you need and you can use it in many +different ways. Because of that, it's broken into many chunks of +code. These chunks (by module name) are: + +ipmi_msghandler - This is the central piece of software for the IPMI +system. It handles all messages, message timing, and responses. The +IPMI users tie into this, and the IPMI physical interfaces (called +System Management Interfaces, or SMIs) also tie in here. This +provides the kernelland interface for IPMI, but does not provide an +interface for use by application processes. + +ipmi_devintf - This provides a userland IOCTL interface for the IPMI +driver, each open file for this device ties in to the message handler +as an IPMI user. + +ipmi_si - A driver for various system interfaces. This supports KCS, +SMIC, and BT interfaces. Unless you have an SMBus interface or your +own custom interface, you probably need to use this. + +ipmi_ssif - A driver for accessing BMCs on the SMBus. It uses the +I2C kernel driver's SMBus interfaces to send and receive IPMI messages +over the SMBus. + +ipmi_powernv - A driver for access BMCs on POWERNV systems. + +ipmi_watchdog - IPMI requires systems to have a very capable watchdog +timer. This driver implements the standard Linux watchdog timer +interface on top of the IPMI message handler. + +ipmi_poweroff - Some systems support the ability to be turned off via +IPMI commands. + +bt-bmc - This is not part of the main driver, but instead a driver for +accessing a BMC-side interface of a BT interface. It is used on BMCs +running Linux to provide an interface to the host. + +These are all individually selectable via configuration options. + +Much documentation for the interface is in the include files. The +IPMI include files are: + +linux/ipmi.h - Contains the user interface and IOCTL interface for IPMI. + +linux/ipmi_smi.h - Contains the interface for system management interfaces +(things that interface to IPMI controllers) to use. + +linux/ipmi_msgdefs.h - General definitions for base IPMI messaging. + + +Addressing +---------- + +The IPMI addressing works much like IP addresses, you have an overlay +to handle the different address types. The overlay is:: + + struct ipmi_addr + { + int addr_type; + short channel; + char data[IPMI_MAX_ADDR_SIZE]; + }; + +The addr_type determines what the address really is. The driver +currently understands two different types of addresses. + +"System Interface" addresses are defined as:: + + struct ipmi_system_interface_addr + { + int addr_type; + short channel; + }; + +and the type is IPMI_SYSTEM_INTERFACE_ADDR_TYPE. This is used for talking +straight to the BMC on the current card. The channel must be +IPMI_BMC_CHANNEL. + +Messages that are destined to go out on the IPMB bus use the +IPMI_IPMB_ADDR_TYPE address type. The format is:: + + struct ipmi_ipmb_addr + { + int addr_type; + short channel; + unsigned char slave_addr; + unsigned char lun; + }; + +The "channel" here is generally zero, but some devices support more +than one channel, it corresponds to the channel as defined in the IPMI +spec. + + +Messages +-------- + +Messages are defined as:: + + struct ipmi_msg + { + unsigned char netfn; + unsigned char lun; + unsigned char cmd; + unsigned char *data; + int data_len; + }; + +The driver takes care of adding/stripping the header information. The +data portion is just the data to be send (do NOT put addressing info +here) or the response. Note that the completion code of a response is +the first item in "data", it is not stripped out because that is how +all the messages are defined in the spec (and thus makes counting the +offsets a little easier :-). + +When using the IOCTL interface from userland, you must provide a block +of data for "data", fill it, and set data_len to the length of the +block of data, even when receiving messages. Otherwise the driver +will have no place to put the message. + +Messages coming up from the message handler in kernelland will come in +as:: + + struct ipmi_recv_msg + { + struct list_head link; + + /* The type of message as defined in the "Receive Types" + defines above. */ + int recv_type; + + ipmi_user_t *user; + struct ipmi_addr addr; + long msgid; + struct ipmi_msg msg; + + /* Call this when done with the message. It will presumably free + the message and do any other necessary cleanup. */ + void (*done)(struct ipmi_recv_msg *msg); + + /* Place-holder for the data, don't make any assumptions about + the size or existence of this, since it may change. */ + unsigned char msg_data[IPMI_MAX_MSG_LENGTH]; + }; + +You should look at the receive type and handle the message +appropriately. + + +The Upper Layer Interface (Message Handler) +------------------------------------------- + +The upper layer of the interface provides the users with a consistent +view of the IPMI interfaces. It allows multiple SMI interfaces to be +addressed (because some boards actually have multiple BMCs on them) +and the user should not have to care what type of SMI is below them. + + +Watching For Interfaces +^^^^^^^^^^^^^^^^^^^^^^^ + +When your code comes up, the IPMI driver may or may not have detected +if IPMI devices exist. So you might have to defer your setup until +the device is detected, or you might be able to do it immediately. +To handle this, and to allow for discovery, you register an SMI +watcher with ipmi_smi_watcher_register() to iterate over interfaces +and tell you when they come and go. + + +Creating the User +^^^^^^^^^^^^^^^^^ + +To use the message handler, you must first create a user using +ipmi_create_user. The interface number specifies which SMI you want +to connect to, and you must supply callback functions to be called +when data comes in. The callback function can run at interrupt level, +so be careful using the callbacks. This also allows to you pass in a +piece of data, the handler_data, that will be passed back to you on +all calls. + +Once you are done, call ipmi_destroy_user() to get rid of the user. + +From userland, opening the device automatically creates a user, and +closing the device automatically destroys the user. + + +Messaging +^^^^^^^^^ + +To send a message from kernel-land, the ipmi_request_settime() call does +pretty much all message handling. Most of the parameter are +self-explanatory. However, it takes a "msgid" parameter. This is NOT +the sequence number of messages. It is simply a long value that is +passed back when the response for the message is returned. You may +use it for anything you like. + +Responses come back in the function pointed to by the ipmi_recv_hndl +field of the "handler" that you passed in to ipmi_create_user(). +Remember again, these may be running at interrupt level. Remember to +look at the receive type, too. + +From userland, you fill out an ipmi_req_t structure and use the +IPMICTL_SEND_COMMAND ioctl. For incoming stuff, you can use select() +or poll() to wait for messages to come in. However, you cannot use +read() to get them, you must call the IPMICTL_RECEIVE_MSG with the +ipmi_recv_t structure to actually get the message. Remember that you +must supply a pointer to a block of data in the msg.data field, and +you must fill in the msg.data_len field with the size of the data. +This gives the receiver a place to actually put the message. + +If the message cannot fit into the data you provide, you will get an +EMSGSIZE error and the driver will leave the data in the receive +queue. If you want to get it and have it truncate the message, us +the IPMICTL_RECEIVE_MSG_TRUNC ioctl. + +When you send a command (which is defined by the lowest-order bit of +the netfn per the IPMI spec) on the IPMB bus, the driver will +automatically assign the sequence number to the command and save the +command. If the response is not receive in the IPMI-specified 5 +seconds, it will generate a response automatically saying the command +timed out. If an unsolicited response comes in (if it was after 5 +seconds, for instance), that response will be ignored. + +In kernelland, after you receive a message and are done with it, you +MUST call ipmi_free_recv_msg() on it, or you will leak messages. Note +that you should NEVER mess with the "done" field of a message, that is +required to properly clean up the message. + +Note that when sending, there is an ipmi_request_supply_msgs() call +that lets you supply the smi and receive message. This is useful for +pieces of code that need to work even if the system is out of buffers +(the watchdog timer uses this, for instance). You supply your own +buffer and own free routines. This is not recommended for normal use, +though, since it is tricky to manage your own buffers. + + +Events and Incoming Commands +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The driver takes care of polling for IPMI events and receiving +commands (commands are messages that are not responses, they are +commands that other things on the IPMB bus have sent you). To receive +these, you must register for them, they will not automatically be sent +to you. + +To receive events, you must call ipmi_set_gets_events() and set the +"val" to non-zero. Any events that have been received by the driver +since startup will immediately be delivered to the first user that +registers for events. After that, if multiple users are registered +for events, they will all receive all events that come in. + +For receiving commands, you have to individually register commands you +want to receive. Call ipmi_register_for_cmd() and supply the netfn +and command name for each command you want to receive. You also +specify a bitmask of the channels you want to receive the command from +(or use IPMI_CHAN_ALL for all channels if you don't care). Only one +user may be registered for each netfn/cmd/channel, but different users +may register for different commands, or the same command if the +channel bitmasks do not overlap. + +From userland, equivalent IOCTLs are provided to do these functions. + + +The Lower Layer (SMI) Interface +------------------------------- + +As mentioned before, multiple SMI interfaces may be registered to the +message handler, each of these is assigned an interface number when +they register with the message handler. They are generally assigned +in the order they register, although if an SMI unregisters and then +another one registers, all bets are off. + +The ipmi_smi.h defines the interface for management interfaces, see +that for more details. + + +The SI Driver +------------- + +The SI driver allows KCS, BT, and SMIC interfaces to be configured +in the system. It discovers interfaces through a host of different +methods, depending on the system. + +You can specify up to four interfaces on the module load line and +control some module parameters:: + + modprobe ipmi_si.o type=<type1>,<type2>.... + ports=<port1>,<port2>... addrs=<addr1>,<addr2>... + irqs=<irq1>,<irq2>... + regspacings=<sp1>,<sp2>,... regsizes=<size1>,<size2>,... + regshifts=<shift1>,<shift2>,... + slave_addrs=<addr1>,<addr2>,... + force_kipmid=<enable1>,<enable2>,... + kipmid_max_busy_us=<ustime1>,<ustime2>,... + unload_when_empty=[0|1] + trydmi=[0|1] tryacpi=[0|1] + tryplatform=[0|1] trypci=[0|1] + +Each of these except try... items is a list, the first item for the +first interface, second item for the second interface, etc. + +The si_type may be either "kcs", "smic", or "bt". If you leave it blank, it +defaults to "kcs". + +If you specify addrs as non-zero for an interface, the driver will +use the memory address given as the address of the device. This +overrides si_ports. + +If you specify ports as non-zero for an interface, the driver will +use the I/O port given as the device address. + +If you specify irqs as non-zero for an interface, the driver will +attempt to use the given interrupt for the device. + +The other try... items disable discovery by their corresponding +names. These are all enabled by default, set them to zero to disable +them. The tryplatform disables openfirmware. + +The next three parameters have to do with register layout. The +registers used by the interfaces may not appear at successive +locations and they may not be in 8-bit registers. These parameters +allow the layout of the data in the registers to be more precisely +specified. + +The regspacings parameter give the number of bytes between successive +register start addresses. For instance, if the regspacing is set to 4 +and the start address is 0xca2, then the address for the second +register would be 0xca6. This defaults to 1. + +The regsizes parameter gives the size of a register, in bytes. The +data used by IPMI is 8-bits wide, but it may be inside a larger +register. This parameter allows the read and write type to specified. +It may be 1, 2, 4, or 8. The default is 1. + +Since the register size may be larger than 32 bits, the IPMI data may not +be in the lower 8 bits. The regshifts parameter give the amount to shift +the data to get to the actual IPMI data. + +The slave_addrs specifies the IPMI address of the local BMC. This is +usually 0x20 and the driver defaults to that, but in case it's not, it +can be specified when the driver starts up. + +The force_ipmid parameter forcefully enables (if set to 1) or disables +(if set to 0) the kernel IPMI daemon. Normally this is auto-detected +by the driver, but systems with broken interrupts might need an enable, +or users that don't want the daemon (don't need the performance, don't +want the CPU hit) can disable it. + +If unload_when_empty is set to 1, the driver will be unloaded if it +doesn't find any interfaces or all the interfaces fail to work. The +default is one. Setting to 0 is useful with the hotmod, but is +obviously only useful for modules. + +When compiled into the kernel, the parameters can be specified on the +kernel command line as:: + + ipmi_si.type=<type1>,<type2>... + ipmi_si.ports=<port1>,<port2>... ipmi_si.addrs=<addr1>,<addr2>... + ipmi_si.irqs=<irq1>,<irq2>... + ipmi_si.regspacings=<sp1>,<sp2>,... + ipmi_si.regsizes=<size1>,<size2>,... + ipmi_si.regshifts=<shift1>,<shift2>,... + ipmi_si.slave_addrs=<addr1>,<addr2>,... + ipmi_si.force_kipmid=<enable1>,<enable2>,... + ipmi_si.kipmid_max_busy_us=<ustime1>,<ustime2>,... + +It works the same as the module parameters of the same names. + +If your IPMI interface does not support interrupts and is a KCS or +SMIC interface, the IPMI driver will start a kernel thread for the +interface to help speed things up. This is a low-priority kernel +thread that constantly polls the IPMI driver while an IPMI operation +is in progress. The force_kipmid module parameter will all the user to +force this thread on or off. If you force it off and don't have +interrupts, the driver will run VERY slowly. Don't blame me, +these interfaces suck. + +Unfortunately, this thread can use a lot of CPU depending on the +interface's performance. This can waste a lot of CPU and cause +various issues with detecting idle CPU and using extra power. To +avoid this, the kipmid_max_busy_us sets the maximum amount of time, in +microseconds, that kipmid will spin before sleeping for a tick. This +value sets a balance between performance and CPU waste and needs to be +tuned to your needs. Maybe, someday, auto-tuning will be added, but +that's not a simple thing and even the auto-tuning would need to be +tuned to the user's desired performance. + +The driver supports a hot add and remove of interfaces. This way, +interfaces can be added or removed after the kernel is up and running. +This is done using /sys/modules/ipmi_si/parameters/hotmod, which is a +write-only parameter. You write a string to this interface. The string +has the format:: + + <op1>[:op2[:op3...]] + +The "op"s are:: + + add|remove,kcs|bt|smic,mem|i/o,<address>[,<opt1>[,<opt2>[,...]]] + +You can specify more than one interface on the line. The "opt"s are:: + + rsp=<regspacing> + rsi=<regsize> + rsh=<regshift> + irq=<irq> + ipmb=<ipmb slave addr> + +and these have the same meanings as discussed above. Note that you +can also use this on the kernel command line for a more compact format +for specifying an interface. Note that when removing an interface, +only the first three parameters (si type, address type, and address) +are used for the comparison. Any options are ignored for removing. + +The SMBus Driver (SSIF) +----------------------- + +The SMBus driver allows up to 4 SMBus devices to be configured in the +system. By default, the driver will only register with something it +finds in DMI or ACPI tables. You can change this +at module load time (for a module) with:: + + modprobe ipmi_ssif.o + addr=<i2caddr1>[,<i2caddr2>[,...]] + adapter=<adapter1>[,<adapter2>[...]] + dbg=<flags1>,<flags2>... + slave_addrs=<addr1>,<addr2>,... + tryacpi=[0|1] trydmi=[0|1] + [dbg_probe=1] + +The addresses are normal I2C addresses. The adapter is the string +name of the adapter, as shown in /sys/class/i2c-adapter/i2c-<n>/name. +It is *NOT* i2c-<n> itself. Also, the comparison is done ignoring +spaces, so if the name is "This is an I2C chip" you can say +adapter_name=ThisisanI2cchip. This is because it's hard to pass in +spaces in kernel parameters. + +The debug flags are bit flags for each BMC found, they are: +IPMI messages: 1, driver state: 2, timing: 4, I2C probe: 8 + +The tryxxx parameters can be used to disable detecting interfaces +from various sources. + +Setting dbg_probe to 1 will enable debugging of the probing and +detection process for BMCs on the SMBusses. + +The slave_addrs specifies the IPMI address of the local BMC. This is +usually 0x20 and the driver defaults to that, but in case it's not, it +can be specified when the driver starts up. + +Discovering the IPMI compliant BMC on the SMBus can cause devices on +the I2C bus to fail. The SMBus driver writes a "Get Device ID" IPMI +message as a block write to the I2C bus and waits for a response. +This action can be detrimental to some I2C devices. It is highly +recommended that the known I2C address be given to the SMBus driver in +the smb_addr parameter unless you have DMI or ACPI data to tell the +driver what to use. + +When compiled into the kernel, the addresses can be specified on the +kernel command line as:: + + ipmb_ssif.addr=<i2caddr1>[,<i2caddr2>[...]] + ipmi_ssif.adapter=<adapter1>[,<adapter2>[...]] + ipmi_ssif.dbg=<flags1>[,<flags2>[...]] + ipmi_ssif.dbg_probe=1 + ipmi_ssif.slave_addrs=<addr1>[,<addr2>[...]] + ipmi_ssif.tryacpi=[0|1] ipmi_ssif.trydmi=[0|1] + +These are the same options as on the module command line. + +The I2C driver does not support non-blocking access or polling, so +this driver cannod to IPMI panic events, extend the watchdog at panic +time, or other panic-related IPMI functions without special kernel +patches and driver modifications. You can get those at the openipmi +web page. + +The driver supports a hot add and remove of interfaces through the I2C +sysfs interface. + +Other Pieces +------------ + +Get the detailed info related with the IPMI device +-------------------------------------------------- + +Some users need more detailed information about a device, like where +the address came from or the raw base device for the IPMI interface. +You can use the IPMI smi_watcher to catch the IPMI interfaces as they +come or go, and to grab the information, you can use the function +ipmi_get_smi_info(), which returns the following structure:: + + struct ipmi_smi_info { + enum ipmi_addr_src addr_src; + struct device *dev; + union { + struct { + void *acpi_handle; + } acpi_info; + } addr_info; + }; + +Currently special info for only for SI_ACPI address sources is +returned. Others may be added as necessary. + +Note that the dev pointer is included in the above structure, and +assuming ipmi_smi_get_info returns success, you must call put_device +on the dev pointer. + + +Watchdog +-------- + +A watchdog timer is provided that implements the Linux-standard +watchdog timer interface. It has three module parameters that can be +used to control it:: + + modprobe ipmi_watchdog timeout=<t> pretimeout=<t> action=<action type> + preaction=<preaction type> preop=<preop type> start_now=x + nowayout=x ifnum_to_use=n panic_wdt_timeout=<t> + +ifnum_to_use specifies which interface the watchdog timer should use. +The default is -1, which means to pick the first one registered. + +The timeout is the number of seconds to the action, and the pretimeout +is the amount of seconds before the reset that the pre-timeout panic will +occur (if pretimeout is zero, then pretimeout will not be enabled). Note +that the pretimeout is the time before the final timeout. So if the +timeout is 50 seconds and the pretimeout is 10 seconds, then the pretimeout +will occur in 40 second (10 seconds before the timeout). The panic_wdt_timeout +is the value of timeout which is set on kernel panic, in order to let actions +such as kdump to occur during panic. + +The action may be "reset", "power_cycle", or "power_off", and +specifies what to do when the timer times out, and defaults to +"reset". + +The preaction may be "pre_smi" for an indication through the SMI +interface, "pre_int" for an indication through the SMI with an +interrupts, and "pre_nmi" for a NMI on a preaction. This is how +the driver is informed of the pretimeout. + +The preop may be set to "preop_none" for no operation on a pretimeout, +"preop_panic" to set the preoperation to panic, or "preop_give_data" +to provide data to read from the watchdog device when the pretimeout +occurs. A "pre_nmi" setting CANNOT be used with "preop_give_data" +because you can't do data operations from an NMI. + +When preop is set to "preop_give_data", one byte comes ready to read +on the device when the pretimeout occurs. Select and fasync work on +the device, as well. + +If start_now is set to 1, the watchdog timer will start running as +soon as the driver is loaded. + +If nowayout is set to 1, the watchdog timer will not stop when the +watchdog device is closed. The default value of nowayout is true +if the CONFIG_WATCHDOG_NOWAYOUT option is enabled, or false if not. + +When compiled into the kernel, the kernel command line is available +for configuring the watchdog:: + + ipmi_watchdog.timeout=<t> ipmi_watchdog.pretimeout=<t> + ipmi_watchdog.action=<action type> + ipmi_watchdog.preaction=<preaction type> + ipmi_watchdog.preop=<preop type> + ipmi_watchdog.start_now=x + ipmi_watchdog.nowayout=x + ipmi_watchdog.panic_wdt_timeout=<t> + +The options are the same as the module parameter options. + +The watchdog will panic and start a 120 second reset timeout if it +gets a pre-action. During a panic or a reboot, the watchdog will +start a 120 timer if it is running to make sure the reboot occurs. + +Note that if you use the NMI preaction for the watchdog, you MUST NOT +use the nmi watchdog. There is no reasonable way to tell if an NMI +comes from the IPMI controller, so it must assume that if it gets an +otherwise unhandled NMI, it must be from IPMI and it will panic +immediately. + +Once you open the watchdog timer, you must write a 'V' character to the +device to close it, or the timer will not stop. This is a new semantic +for the driver, but makes it consistent with the rest of the watchdog +drivers in Linux. + + +Panic Timeouts +-------------- + +The OpenIPMI driver supports the ability to put semi-custom and custom +events in the system event log if a panic occurs. if you enable the +'Generate a panic event to all BMCs on a panic' option, you will get +one event on a panic in a standard IPMI event format. If you enable +the 'Generate OEM events containing the panic string' option, you will +also get a bunch of OEM events holding the panic string. + + +The field settings of the events are: + +* Generator ID: 0x21 (kernel) +* EvM Rev: 0x03 (this event is formatting in IPMI 1.0 format) +* Sensor Type: 0x20 (OS critical stop sensor) +* Sensor #: The first byte of the panic string (0 if no panic string) +* Event Dir | Event Type: 0x6f (Assertion, sensor-specific event info) +* Event Data 1: 0xa1 (Runtime stop in OEM bytes 2 and 3) +* Event data 2: second byte of panic string +* Event data 3: third byte of panic string + +See the IPMI spec for the details of the event layout. This event is +always sent to the local management controller. It will handle routing +the message to the right place + +Other OEM events have the following format: + +* Record ID (bytes 0-1): Set by the SEL. +* Record type (byte 2): 0xf0 (OEM non-timestamped) +* byte 3: The slave address of the card saving the panic +* byte 4: A sequence number (starting at zero) + The rest of the bytes (11 bytes) are the panic string. If the panic string + is longer than 11 bytes, multiple messages will be sent with increasing + sequence numbers. + +Because you cannot send OEM events using the standard interface, this +function will attempt to find an SEL and add the events there. It +will first query the capabilities of the local management controller. +If it has an SEL, then they will be stored in the SEL of the local +management controller. If not, and the local management controller is +an event generator, the event receiver from the local management +controller will be queried and the events sent to the SEL on that +device. Otherwise, the events go nowhere since there is nowhere to +send them. + + +Poweroff +-------- + +If the poweroff capability is selected, the IPMI driver will install +a shutdown function into the standard poweroff function pointer. This +is in the ipmi_poweroff module. When the system requests a powerdown, +it will send the proper IPMI commands to do this. This is supported on +several platforms. + +There is a module parameter named "poweroff_powercycle" that may +either be zero (do a power down) or non-zero (do a power cycle, power +the system off, then power it on in a few seconds). Setting +ipmi_poweroff.poweroff_control=x will do the same thing on the kernel +command line. The parameter is also available via the proc filesystem +in /proc/sys/dev/ipmi/poweroff_powercycle. Note that if the system +does not support power cycling, it will always do the power off. + +The "ifnum_to_use" parameter specifies which interface the poweroff +code should use. The default is -1, which means to pick the first one +registered. + +Note that if you have ACPI enabled, the system will prefer using ACPI to +power off. diff --git a/Documentation/driver-api/media/cec-core.rst b/Documentation/driver-api/media/cec-core.rst new file mode 100644 index 000000000000..3ce26b7c2b2b --- /dev/null +++ b/Documentation/driver-api/media/cec-core.rst @@ -0,0 +1,474 @@ +.. SPDX-License-Identifier: GPL-2.0 + +CEC Kernel Support +================== + +The CEC framework provides a unified kernel interface for use with HDMI CEC +hardware. It is designed to handle a multiple types of hardware (receivers, +transmitters, USB dongles). The framework also gives the option to decide +what to do in the kernel driver and what should be handled by userspace +applications. In addition it integrates the remote control passthrough +feature into the kernel's remote control framework. + + +The CEC Protocol +---------------- + +The CEC protocol enables consumer electronic devices to communicate with each +other through the HDMI connection. The protocol uses logical addresses in the +communication. The logical address is strictly connected with the functionality +provided by the device. The TV acting as the communication hub is always +assigned address 0. The physical address is determined by the physical +connection between devices. + +The CEC framework described here is up to date with the CEC 2.0 specification. +It is documented in the HDMI 1.4 specification with the new 2.0 bits documented +in the HDMI 2.0 specification. But for most of the features the freely available +HDMI 1.3a specification is sufficient: + +http://www.microprocessor.org/HDMISpecification13a.pdf + + +CEC Adapter Interface +--------------------- + +The struct cec_adapter represents the CEC adapter hardware. It is created by +calling cec_allocate_adapter() and deleted by calling cec_delete_adapter(): + +.. c:function:: + struct cec_adapter *cec_allocate_adapter(const struct cec_adap_ops *ops, void *priv, + const char *name, u32 caps, u8 available_las); + +.. c:function:: + void cec_delete_adapter(struct cec_adapter *adap); + +To create an adapter you need to pass the following information: + +ops: + adapter operations which are called by the CEC framework and that you + have to implement. + +priv: + will be stored in adap->priv and can be used by the adapter ops. + Use cec_get_drvdata(adap) to get the priv pointer. + +name: + the name of the CEC adapter. Note: this name will be copied. + +caps: + capabilities of the CEC adapter. These capabilities determine the + capabilities of the hardware and which parts are to be handled + by userspace and which parts are handled by kernelspace. The + capabilities are returned by CEC_ADAP_G_CAPS. + +available_las: + the number of simultaneous logical addresses that this + adapter can handle. Must be 1 <= available_las <= CEC_MAX_LOG_ADDRS. + +To obtain the priv pointer use this helper function: + +.. c:function:: + void *cec_get_drvdata(const struct cec_adapter *adap); + +To register the /dev/cecX device node and the remote control device (if +CEC_CAP_RC is set) you call: + +.. c:function:: + int cec_register_adapter(struct cec_adapter *adap, struct device *parent); + +where parent is the parent device. + +To unregister the devices call: + +.. c:function:: + void cec_unregister_adapter(struct cec_adapter *adap); + +Note: if cec_register_adapter() fails, then call cec_delete_adapter() to +clean up. But if cec_register_adapter() succeeded, then only call +cec_unregister_adapter() to clean up, never cec_delete_adapter(). The +unregister function will delete the adapter automatically once the last user +of that /dev/cecX device has closed its file handle. + + +Implementing the Low-Level CEC Adapter +-------------------------------------- + +The following low-level adapter operations have to be implemented in +your driver: + +.. c:type:: struct cec_adap_ops + +.. code-block:: none + + struct cec_adap_ops + { + /* Low-level callbacks */ + int (*adap_enable)(struct cec_adapter *adap, bool enable); + int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable); + int (*adap_monitor_pin_enable)(struct cec_adapter *adap, bool enable); + int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr); + int (*adap_transmit)(struct cec_adapter *adap, u8 attempts, + u32 signal_free_time, struct cec_msg *msg); + void (*adap_status)(struct cec_adapter *adap, struct seq_file *file); + void (*adap_free)(struct cec_adapter *adap); + + /* Error injection callbacks */ + ... + + /* High-level callbacks */ + ... + }; + +The seven low-level ops deal with various aspects of controlling the CEC adapter +hardware: + + +To enable/disable the hardware: + +.. c:function:: + int (*adap_enable)(struct cec_adapter *adap, bool enable); + +This callback enables or disables the CEC hardware. Enabling the CEC hardware +means powering it up in a state where no logical addresses are claimed. This +op assumes that the physical address (adap->phys_addr) is valid when enable is +true and will not change while the CEC adapter remains enabled. The initial +state of the CEC adapter after calling cec_allocate_adapter() is disabled. + +Note that adap_enable must return 0 if enable is false. + + +To enable/disable the 'monitor all' mode: + +.. c:function:: + int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable); + +If enabled, then the adapter should be put in a mode to also monitor messages +that not for us. Not all hardware supports this and this function is only +called if the CEC_CAP_MONITOR_ALL capability is set. This callback is optional +(some hardware may always be in 'monitor all' mode). + +Note that adap_monitor_all_enable must return 0 if enable is false. + + +To enable/disable the 'monitor pin' mode: + +.. c:function:: + int (*adap_monitor_pin_enable)(struct cec_adapter *adap, bool enable); + +If enabled, then the adapter should be put in a mode to also monitor CEC pin +changes. Not all hardware supports this and this function is only called if +the CEC_CAP_MONITOR_PIN capability is set. This callback is optional +(some hardware may always be in 'monitor pin' mode). + +Note that adap_monitor_pin_enable must return 0 if enable is false. + + +To program a new logical address: + +.. c:function:: + int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr); + +If logical_addr == CEC_LOG_ADDR_INVALID then all programmed logical addresses +are to be erased. Otherwise the given logical address should be programmed. +If the maximum number of available logical addresses is exceeded, then it +should return -ENXIO. Once a logical address is programmed the CEC hardware +can receive directed messages to that address. + +Note that adap_log_addr must return 0 if logical_addr is CEC_LOG_ADDR_INVALID. + + +To transmit a new message: + +.. c:function:: + int (*adap_transmit)(struct cec_adapter *adap, u8 attempts, + u32 signal_free_time, struct cec_msg *msg); + +This transmits a new message. The attempts argument is the suggested number of +attempts for the transmit. + +The signal_free_time is the number of data bit periods that the adapter should +wait when the line is free before attempting to send a message. This value +depends on whether this transmit is a retry, a message from a new initiator or +a new message for the same initiator. Most hardware will handle this +automatically, but in some cases this information is needed. + +The CEC_FREE_TIME_TO_USEC macro can be used to convert signal_free_time to +microseconds (one data bit period is 2.4 ms). + + +To log the current CEC hardware status: + +.. c:function:: + void (*adap_status)(struct cec_adapter *adap, struct seq_file *file); + +This optional callback can be used to show the status of the CEC hardware. +The status is available through debugfs: cat /sys/kernel/debug/cec/cecX/status + +To free any resources when the adapter is deleted: + +.. c:function:: + void (*adap_free)(struct cec_adapter *adap); + +This optional callback can be used to free any resources that might have been +allocated by the driver. It's called from cec_delete_adapter. + + +Your adapter driver will also have to react to events (typically interrupt +driven) by calling into the framework in the following situations: + +When a transmit finished (successfully or otherwise): + +.. c:function:: + void cec_transmit_done(struct cec_adapter *adap, u8 status, u8 arb_lost_cnt, + u8 nack_cnt, u8 low_drive_cnt, u8 error_cnt); + +or: + +.. c:function:: + void cec_transmit_attempt_done(struct cec_adapter *adap, u8 status); + +The status can be one of: + +CEC_TX_STATUS_OK: + the transmit was successful. + +CEC_TX_STATUS_ARB_LOST: + arbitration was lost: another CEC initiator + took control of the CEC line and you lost the arbitration. + +CEC_TX_STATUS_NACK: + the message was nacked (for a directed message) or + acked (for a broadcast message). A retransmission is needed. + +CEC_TX_STATUS_LOW_DRIVE: + low drive was detected on the CEC bus. This indicates that + a follower detected an error on the bus and requested a + retransmission. + +CEC_TX_STATUS_ERROR: + some unspecified error occurred: this can be one of ARB_LOST + or LOW_DRIVE if the hardware cannot differentiate or something + else entirely. Some hardware only supports OK and FAIL as the + result of a transmit, i.e. there is no way to differentiate + between the different possible errors. In that case map FAIL + to CEC_TX_STATUS_NACK and not to CEC_TX_STATUS_ERROR. + +CEC_TX_STATUS_MAX_RETRIES: + could not transmit the message after trying multiple times. + Should only be set by the driver if it has hardware support for + retrying messages. If set, then the framework assumes that it + doesn't have to make another attempt to transmit the message + since the hardware did that already. + +The hardware must be able to differentiate between OK, NACK and 'something +else'. + +The \*_cnt arguments are the number of error conditions that were seen. +This may be 0 if no information is available. Drivers that do not support +hardware retry can just set the counter corresponding to the transmit error +to 1, if the hardware does support retry then either set these counters to +0 if the hardware provides no feedback of which errors occurred and how many +times, or fill in the correct values as reported by the hardware. + +Be aware that calling these functions can immediately start a new transmit +if there is one pending in the queue. So make sure that the hardware is in +a state where new transmits can be started *before* calling these functions. + +The cec_transmit_attempt_done() function is a helper for cases where the +hardware never retries, so the transmit is always for just a single +attempt. It will call cec_transmit_done() in turn, filling in 1 for the +count argument corresponding to the status. Or all 0 if the status was OK. + +When a CEC message was received: + +.. c:function:: + void cec_received_msg(struct cec_adapter *adap, struct cec_msg *msg); + +Speaks for itself. + +Implementing the interrupt handler +---------------------------------- + +Typically the CEC hardware provides interrupts that signal when a transmit +finished and whether it was successful or not, and it provides and interrupt +when a CEC message was received. + +The CEC driver should always process the transmit interrupts first before +handling the receive interrupt. The framework expects to see the cec_transmit_done +call before the cec_received_msg call, otherwise it can get confused if the +received message was in reply to the transmitted message. + +Optional: Implementing Error Injection Support +---------------------------------------------- + +If the CEC adapter supports Error Injection functionality, then that can +be exposed through the Error Injection callbacks: + +.. code-block:: none + + struct cec_adap_ops { + /* Low-level callbacks */ + ... + + /* Error injection callbacks */ + int (*error_inj_show)(struct cec_adapter *adap, struct seq_file *sf); + bool (*error_inj_parse_line)(struct cec_adapter *adap, char *line); + + /* High-level CEC message callback */ + ... + }; + +If both callbacks are set, then an ``error-inj`` file will appear in debugfs. +The basic syntax is as follows: + +Leading spaces/tabs are ignored. If the next character is a ``#`` or the end of the +line was reached, then the whole line is ignored. Otherwise a command is expected. + +This basic parsing is done in the CEC Framework. It is up to the driver to decide +what commands to implement. The only requirement is that the command ``clear`` without +any arguments must be implemented and that it will remove all current error injection +commands. + +This ensures that you can always do ``echo clear >error-inj`` to clear any error +injections without having to know the details of the driver-specific commands. + +Note that the output of ``error-inj`` shall be valid as input to ``error-inj``. +So this must work: + +.. code-block:: none + + $ cat error-inj >einj.txt + $ cat einj.txt >error-inj + +The first callback is called when this file is read and it should show the +the current error injection state: + +.. c:function:: + int (*error_inj_show)(struct cec_adapter *adap, struct seq_file *sf); + +It is recommended that it starts with a comment block with basic usage +information. It returns 0 for success and an error otherwise. + +The second callback will parse commands written to the ``error-inj`` file: + +.. c:function:: + bool (*error_inj_parse_line)(struct cec_adapter *adap, char *line); + +The ``line`` argument points to the start of the command. Any leading +spaces or tabs have already been skipped. It is a single line only (so there +are no embedded newlines) and it is 0-terminated. The callback is free to +modify the contents of the buffer. It is only called for lines containing a +command, so this callback is never called for empty lines or comment lines. + +Return true if the command was valid or false if there were syntax errors. + +Implementing the High-Level CEC Adapter +--------------------------------------- + +The low-level operations drive the hardware, the high-level operations are +CEC protocol driven. The following high-level callbacks are available: + +.. code-block:: none + + struct cec_adap_ops { + /* Low-level callbacks */ + ... + + /* Error injection callbacks */ + ... + + /* High-level CEC message callback */ + int (*received)(struct cec_adapter *adap, struct cec_msg *msg); + }; + +The received() callback allows the driver to optionally handle a newly +received CEC message + +.. c:function:: + int (*received)(struct cec_adapter *adap, struct cec_msg *msg); + +If the driver wants to process a CEC message, then it can implement this +callback. If it doesn't want to handle this message, then it should return +-ENOMSG, otherwise the CEC framework assumes it processed this message and +it will not do anything with it. + + +CEC framework functions +----------------------- + +CEC Adapter drivers can call the following CEC framework functions: + +.. c:function:: + int cec_transmit_msg(struct cec_adapter *adap, struct cec_msg *msg, + bool block); + +Transmit a CEC message. If block is true, then wait until the message has been +transmitted, otherwise just queue it and return. + +.. c:function:: + void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr, + bool block); + +Change the physical address. This function will set adap->phys_addr and +send an event if it has changed. If cec_s_log_addrs() has been called and +the physical address has become valid, then the CEC framework will start +claiming the logical addresses. If block is true, then this function won't +return until this process has finished. + +When the physical address is set to a valid value the CEC adapter will +be enabled (see the adap_enable op). When it is set to CEC_PHYS_ADDR_INVALID, +then the CEC adapter will be disabled. If you change a valid physical address +to another valid physical address, then this function will first set the +address to CEC_PHYS_ADDR_INVALID before enabling the new physical address. + +.. c:function:: + void cec_s_phys_addr_from_edid(struct cec_adapter *adap, + const struct edid *edid); + +A helper function that extracts the physical address from the edid struct +and calls cec_s_phys_addr() with that address, or CEC_PHYS_ADDR_INVALID +if the EDID did not contain a physical address or edid was a NULL pointer. + +.. c:function:: + int cec_s_log_addrs(struct cec_adapter *adap, + struct cec_log_addrs *log_addrs, bool block); + +Claim the CEC logical addresses. Should never be called if CEC_CAP_LOG_ADDRS +is set. If block is true, then wait until the logical addresses have been +claimed, otherwise just queue it and return. To unconfigure all logical +addresses call this function with log_addrs set to NULL or with +log_addrs->num_log_addrs set to 0. The block argument is ignored when +unconfiguring. This function will just return if the physical address is +invalid. Once the physical address becomes valid, then the framework will +attempt to claim these logical addresses. + +CEC Pin framework +----------------- + +Most CEC hardware operates on full CEC messages where the software provides +the message and the hardware handles the low-level CEC protocol. But some +hardware only drives the CEC pin and software has to handle the low-level +CEC protocol. The CEC pin framework was created to handle such devices. + +Note that due to the close-to-realtime requirements it can never be guaranteed +to work 100%. This framework uses highres timers internally, but if a +timer goes off too late by more than 300 microseconds wrong results can +occur. In reality it appears to be fairly reliable. + +One advantage of this low-level implementation is that it can be used as +a cheap CEC analyser, especially if interrupts can be used to detect +CEC pin transitions from low to high or vice versa. + +.. kernel-doc:: include/media/cec-pin.h + +CEC Notifier framework +---------------------- + +Most drm HDMI implementations have an integrated CEC implementation and no +notifier support is needed. But some have independent CEC implementations +that have their own driver. This could be an IP block for an SoC or a +completely separate chip that deals with the CEC pin. For those cases a +drm driver can install a notifier and use the notifier to inform the +CEC driver about changes in the physical address. + +.. kernel-doc:: include/media/cec-notifier.h diff --git a/Documentation/driver-api/media/csi2.rst b/Documentation/driver-api/media/csi2.rst new file mode 100644 index 000000000000..17cad435f1a0 --- /dev/null +++ b/Documentation/driver-api/media/csi2.rst @@ -0,0 +1,91 @@ +.. SPDX-License-Identifier: GPL-2.0 + +MIPI CSI-2 +========== + +CSI-2 is a data bus intended for transferring images from cameras to +the host SoC. It is defined by the `MIPI alliance`_. + +.. _`MIPI alliance`: http://www.mipi.org/ + +Media bus formats +----------------- + +See :ref:`v4l2-mbus-pixelcode` for details on which media bus formats should +be used for CSI-2 interfaces. + +Transmitter drivers +------------------- + +CSI-2 transmitter, such as a sensor or a TV tuner, drivers need to +provide the CSI-2 receiver with information on the CSI-2 bus +configuration. These include the V4L2_CID_LINK_FREQ and +V4L2_CID_PIXEL_RATE controls and +(:c:type:`v4l2_subdev_video_ops`->s_stream() callback). These +interface elements must be present on the sub-device represents the +CSI-2 transmitter. + +The V4L2_CID_LINK_FREQ control is used to tell the receiver driver the +frequency (and not the symbol rate) of the link. The +V4L2_CID_PIXEL_RATE is may be used by the receiver to obtain the pixel +rate the transmitter uses. The +:c:type:`v4l2_subdev_video_ops`->s_stream() callback provides an +ability to start and stop the stream. + +The value of the V4L2_CID_PIXEL_RATE is calculated as follows:: + + pixel_rate = link_freq * 2 * nr_of_lanes / bits_per_sample + +where + +.. list-table:: variables in pixel rate calculation + :header-rows: 1 + + * - variable or constant + - description + * - link_freq + - The value of the V4L2_CID_LINK_FREQ integer64 menu item. + * - nr_of_lanes + - Number of data lanes used on the CSI-2 link. This can + be obtained from the OF endpoint configuration. + * - 2 + - Two bits are transferred per clock cycle per lane. + * - bits_per_sample + - Number of bits per sample. + +The transmitter drivers must, if possible, configure the CSI-2 +transmitter to *LP-11 mode* whenever the transmitter is powered on but +not active, and maintain *LP-11 mode* until stream on. Only at stream +on should the transmitter activate the clock on the clock lane and +transition to *HS mode*. + +Some transmitters do this automatically but some have to be explicitly +programmed to do so, and some are unable to do so altogether due to +hardware constraints. + +Stopping the transmitter +^^^^^^^^^^^^^^^^^^^^^^^^ + +A transmitter stops sending the stream of images as a result of +calling the ``.s_stream()`` callback. Some transmitters may stop the +stream at a frame boundary whereas others stop immediately, +effectively leaving the current frame unfinished. The receiver driver +should not make assumptions either way, but function properly in both +cases. + +Receiver drivers +---------------- + +Before the receiver driver may enable the CSI-2 transmitter by using +the :c:type:`v4l2_subdev_video_ops`->s_stream(), it must have powered +the transmitter up by using the +:c:type:`v4l2_subdev_core_ops`->s_power() callback. This may take +place either indirectly by using :c:func:`v4l2_pipeline_pm_get` or +directly. + +Formats +------- + +The media bus pixel codes document parallel formats. Should the pixel data be +transported over a serial bus, the media bus pixel code that describes a +parallel format that transfers a sample on a single clock cycle is used. diff --git a/Documentation/driver-api/media/drivers/bttv-devel.rst b/Documentation/driver-api/media/drivers/bttv-devel.rst new file mode 100644 index 000000000000..c9aa8b95a5e5 --- /dev/null +++ b/Documentation/driver-api/media/drivers/bttv-devel.rst @@ -0,0 +1,116 @@ +.. SPDX-License-Identifier: GPL-2.0 + +The bttv driver +=============== + +bttv and sound mini howto +------------------------- + +There are a lot of different bt848/849/878/879 based boards available. +Making video work often is not a big deal, because this is handled +completely by the bt8xx chip, which is common on all boards. But +sound is handled in slightly different ways on each board. + +To handle the grabber boards correctly, there is a array tvcards[] in +bttv-cards.c, which holds the information required for each board. +Sound will work only, if the correct entry is used (for video it often +makes no difference). The bttv driver prints a line to the kernel +log, telling which card type is used. Like this one:: + + bttv0: model: BT848(Hauppauge old) [autodetected] + +You should verify this is correct. If it isn't, you have to pass the +correct board type as insmod argument, ``insmod bttv card=2`` for +example. The file :doc:`/admin-guide/media/bttv-cardlist` has a list +of valid arguments for card. + +If your card isn't listed there, you might check the source code for +new entries which are not listed yet. If there isn't one for your +card, you can check if one of the existing entries does work for you +(just trial and error...). + +Some boards have an extra processor for sound to do stereo decoding +and other nice features. The msp34xx chips are used by Hauppauge for +example. If your board has one, you might have to load a helper +module like ``msp3400`` to make sound work. If there isn't one for the +chip used on your board: Bad luck. Start writing a new one. Well, +you might want to check the video4linux mailing list archive first... + +Of course you need a correctly installed soundcard unless you have the +speakers connected directly to the grabber board. Hint: check the +mixer settings too. ALSA for example has everything muted by default. + + +How sound works in detail +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Still doesn't work? Looks like some driver hacking is required. +Below is a do-it-yourself description for you. + +The bt8xx chips have 32 general purpose pins, and registers to control +these pins. One register is the output enable register +(``BT848_GPIO_OUT_EN``), it says which pins are actively driven by the +bt848 chip. Another one is the data register (``BT848_GPIO_DATA``), where +you can get/set the status if these pins. They can be used for input +and output. + +Most grabber board vendors use these pins to control an external chip +which does the sound routing. But every board is a little different. +These pins are also used by some companies to drive remote control +receiver chips. Some boards use the i2c bus instead of the gpio pins +to connect the mux chip. + +As mentioned above, there is a array which holds the required +information for each known board. You basically have to create a new +line for your board. The important fields are these two:: + + struct tvcard + { + [ ... ] + u32 gpiomask; + u32 audiomux[6]; /* Tuner, Radio, external, internal, mute, stereo */ + }; + +gpiomask specifies which pins are used to control the audio mux chip. +The corresponding bits in the output enable register +(``BT848_GPIO_OUT_EN``) will be set as these pins must be driven by the +bt848 chip. + +The ``audiomux[]`` array holds the data values for the different inputs +(i.e. which pins must be high/low for tuner/mute/...). This will be +written to the data register (``BT848_GPIO_DATA``) to switch the audio +mux. + + +What you have to do is figure out the correct values for gpiomask and +the audiomux array. If you have Windows and the drivers four your +card installed, you might to check out if you can read these registers +values used by the windows driver. A tool to do this is available +from http://btwincap.sourceforge.net/download.html. + +You might also dig around in the ``*.ini`` files of the Windows applications. +You can have a look at the board to see which of the gpio pins are +connected at all and then start trial-and-error ... + + +Starting with release 0.7.41 bttv has a number of insmod options to +make the gpio debugging easier: + + ================= ============================================== + bttv_gpio=0/1 enable/disable gpio debug messages + gpiomask=n set the gpiomask value + audiomux=i,j,... set the values of the audiomux array + audioall=a set the values of the audiomux array (one + value for all array elements, useful to check + out which effect the particular value has). + ================= ============================================== + +The messages printed with ``bttv_gpio=1`` look like this:: + + bttv0: gpio: en=00000027, out=00000024 in=00ffffd8 [audio: off] + + en = output _en_able register (BT848_GPIO_OUT_EN) + out = _out_put bits of the data register (BT848_GPIO_DATA), + i.e. BT848_GPIO_DATA & BT848_GPIO_OUT_EN + in = _in_put bits of the data register, + i.e. BT848_GPIO_DATA & ~BT848_GPIO_OUT_EN diff --git a/Documentation/driver-api/media/drivers/contributors.rst b/Documentation/driver-api/media/drivers/contributors.rst new file mode 100644 index 000000000000..f23b6e6faf46 --- /dev/null +++ b/Documentation/driver-api/media/drivers/contributors.rst @@ -0,0 +1,131 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Contributors +============ + +.. note:: + + This documentation is outdated. There are several other DVB contributors + that aren't listed below. + +Thanks go to the following people for patches and contributions: + +- Michael Hunold <m.hunold@gmx.de> + + - for the initial saa7146 driver and its recent overhaul + +- Christian Theiss + + - for his work on the initial Linux DVB driver + +- Marcus Metzler <mocm@metzlerbros.de> and + Ralph Metzler <rjkm@metzlerbros.de> + + - for their continuing work on the DVB driver + +- Michael Holzt <kju@debian.org> + + - for his contributions to the dvb-net driver + +- Diego Picciani <d.picciani@novacomp.it> + + - for CyberLogin for Linux which allows logging onto EON + (in case you are wondering where CyberLogin is, EON changed its login + procedure and CyberLogin is no longer used.) + +- Martin Schaller <martin@smurf.franken.de> + + - for patching the cable card decoder driver + +- Klaus Schmidinger <Klaus.Schmidinger@cadsoft.de> + + - for various fixes regarding tuning, OSD and CI stuff and his work on VDR + +- Steve Brown <sbrown@cortland.com> + + - for his AFC kernel thread + +- Christoph Martin <martin@uni-mainz.de> + + - for his LIRC infrared handler + +- Andreas Oberritter <obi@linuxtv.org>, + Dennis Noermann <dennis.noermann@noernet.de>, + Felix Domke <tmbinc@elitedvb.net>, + Florian Schirmer <jolt@tuxbox.org>, + Ronny Strutz <3des@elitedvb.de>, + Wolfram Joost <dbox2@frokaschwei.de> + and all the other dbox2 people + + - for many bugfixes in the generic DVB Core, frontend drivers and + their work on the dbox2 port of the DVB driver + +- Oliver Endriss <o.endriss@gmx.de> + + - for many bugfixes + +- Andrew de Quincey <adq_dvb@lidskialf.net> + + - for the tda1004x frontend driver, and various bugfixes + +- Peter Schildmann <peter.schildmann@web.de> + + - for the driver for the Technisat SkyStar2 PCI DVB card + +- Vadim Catana <skystar@moldova.cc>, + Roberto Ragusa <r.ragusa@libero.it> and + Augusto Cardoso <augusto@carhil.net> + + - for all the work for the FlexCopII chipset by B2C2,Inc. + +- Davor Emard <emard@softhome.net> + + - for his work on the budget drivers, the demux code, + the module unloading problems, ... + +- Hans-Frieder Vogt <hfvogt@arcor.de> + + - for his work on calculating and checking the crc's for the + TechnoTrend/Hauppauge DEC driver firmware + +- Michael Dreher <michael@5dot1.de> and + Andreas 'randy' Weinberger + + - for the support of the Fujitsu-Siemens Activy budget DVB-S + +- Kenneth Aafløy <ke-aa@frisurf.no> + + - for adding support for Typhoon DVB-S budget card + +- Ernst Peinlich <e.peinlich@inode.at> + + - for tuning/DiSEqC support for the DEC 3000-s + +- Peter Beutner <p.beutner@gmx.net> + + - for the IR code for the ttusb-dec driver + +- Wilson Michaels <wilsonmichaels@earthlink.net> + + - for the lgdt330x frontend driver, and various bugfixes + +- Michael Krufky <mkrufky@linuxtv.org> + + - for maintaining v4l/dvb inter-tree dependencies + +- Taylor Jacob <rtjacob@earthlink.net> + + - for the nxt2002 frontend driver + +- Jean-Francois Thibert <jeanfrancois@sagetv.com> + + - for the nxt2004 frontend driver + +- Kirk Lapray <kirk.lapray@gmail.com> + + - for the or51211 and or51132 frontend drivers, and + for merging the nxt2002 and nxt2004 modules into a + single nxt200x frontend driver. + +(If you think you should be in this list, but you are not, drop a +line to the DVB mailing list) diff --git a/Documentation/driver-api/media/drivers/cpia2_devel.rst b/Documentation/driver-api/media/drivers/cpia2_devel.rst new file mode 100644 index 000000000000..decaa4768c78 --- /dev/null +++ b/Documentation/driver-api/media/drivers/cpia2_devel.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GPL-2.0 + +The cpia2 driver +================ + +Authors: Peter Pregler <Peter_Pregler@email.com>, +Scott J. Bertin <scottbertin@yahoo.com>, and +Jarl Totland <Jarl.Totland@bdc.no> for the original cpia driver, which +this one was modelled from. + + +Notes to developers +~~~~~~~~~~~~~~~~~~~ + + - This is a driver version stripped of the 2.4 back compatibility + and old MJPEG ioctl API. See cpia2.sf.net for 2.4 support. + +Programmer's overview of cpia2 driver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Cpia2 is the second generation video coprocessor from VLSI Vision Ltd (now a +division of ST Microelectronics). There are two versions. The first is the +STV0672, which is capable of up to 30 frames per second (fps) in frame sizes +up to CIF, and 15 fps for VGA frames. The STV0676 is an improved version, +which can handle up to 30 fps VGA. Both coprocessors can be attached to two +CMOS sensors - the vvl6410 CIF sensor and the vvl6500 VGA sensor. These will +be referred to as the 410 and the 500 sensors, or the CIF and VGA sensors. + +The two chipsets operate almost identically. The core is an 8051 processor, +running two different versions of firmware. The 672 runs the VP4 video +processor code, the 676 runs VP5. There are a few differences in register +mappings for the two chips. In these cases, the symbols defined in the +header files are marked with VP4 or VP5 as part of the symbol name. + +The cameras appear externally as three sets of registers. Setting register +values is the only way to control the camera. Some settings are +interdependant, such as the sequence required to power up the camera. I will +try to make note of all of these cases. + +The register sets are called blocks. Block 0 is the system block. This +section is always powered on when the camera is plugged in. It contains +registers that control housekeeping functions such as powering up the video +processor. The video processor is the VP block. These registers control +how the video from the sensor is processed. Examples are timing registers, +user mode (vga, qvga), scaling, cropping, framerates, and so on. The last +block is the video compressor (VC). The video stream sent from the camera is +compressed as Motion JPEG (JPEGA). The VC controls all of the compression +parameters. Looking at the file cpia2_registers.h, you can get a full view +of these registers and the possible values for most of them. + +One or more registers can be set or read by sending a usb control message to +the camera. There are three modes for this. Block mode requests a number +of contiguous registers. Random mode reads or writes random registers with +a tuple structure containing address/value pairs. The repeat mode is only +used by VP4 to load a firmware patch. It contains a starting address and +a sequence of bytes to be written into a gpio port. diff --git a/Documentation/driver-api/media/drivers/cx2341x-devel.rst b/Documentation/driver-api/media/drivers/cx2341x-devel.rst new file mode 100644 index 000000000000..97699df6ea2e --- /dev/null +++ b/Documentation/driver-api/media/drivers/cx2341x-devel.rst @@ -0,0 +1,3685 @@ +.. SPDX-License-Identifier: GPL-2.0 + +The cx2341x driver +================== + +Memory at cx2341x chips +----------------------- + +This section describes the cx2341x memory map and documents some of the +register space. + +.. note:: the memory long words are little-endian ('intel format'). + +.. warning:: + + This information was figured out from searching through the memory + and registers, this information may not be correct and is certainly + not complete, and was not derived from anything more than searching + through the memory space with commands like: + + .. code-block:: none + + ivtvctl -O min=0x02000000,max=0x020000ff + + So take this as is, I'm always searching for more stuff, it's a large + register space :-). + +Memory Map +~~~~~~~~~~ + +The cx2341x exposes its entire 64M memory space to the PCI host via the PCI BAR0 +(Base Address Register 0). The addresses here are offsets relative to the +address held in BAR0. + +.. code-block:: none + + 0x00000000-0x00ffffff Encoder memory space + 0x00000000-0x0003ffff Encode.rom + ???-??? MPEG buffer(s) + ???-??? Raw video capture buffer(s) + ???-??? Raw audio capture buffer(s) + ???-??? Display buffers (6 or 9) + + 0x01000000-0x01ffffff Decoder memory space + 0x01000000-0x0103ffff Decode.rom + ???-??? MPEG buffers(s) + 0x0114b000-0x0115afff Audio.rom (deprecated?) + + 0x02000000-0x0200ffff Register Space + +Registers +~~~~~~~~~ + +The registers occupy the 64k space starting at the 0x02000000 offset from BAR0. +All of these registers are 32 bits wide. + +.. code-block:: none + + DMA Registers 0x000-0xff: + + 0x00 - Control: + 0=reset/cancel, 1=read, 2=write, 4=stop + 0x04 - DMA status: + 1=read busy, 2=write busy, 4=read error, 8=write error, 16=link list error + 0x08 - pci DMA pointer for read link list + 0x0c - pci DMA pointer for write link list + 0x10 - read/write DMA enable: + 1=read enable, 2=write enable + 0x14 - always 0xffffffff, if set any lower instability occurs, 0x00 crashes + 0x18 - ?? + 0x1c - always 0x20 or 32, smaller values slow down DMA transactions + 0x20 - always value of 0x780a010a + 0x24-0x3c - usually just random values??? + 0x40 - Interrupt status + 0x44 - Write a bit here and shows up in Interrupt status 0x40 + 0x48 - Interrupt Mask + 0x4C - always value of 0xfffdffff, + if changed to 0xffffffff DMA write interrupts break. + 0x50 - always 0xffffffff + 0x54 - always 0xffffffff (0x4c, 0x50, 0x54 seem like interrupt masks, are + 3 processors on chip, Java ones, VPU, SPU, APU, maybe these are the + interrupt masks???). + 0x60-0x7C - random values + 0x80 - first write linked list reg, for Encoder Memory addr + 0x84 - first write linked list reg, for pci memory addr + 0x88 - first write linked list reg, for length of buffer in memory addr + (|0x80000000 or this for last link) + 0x8c-0xdc - rest of write linked list reg, 8 sets of 3 total, DMA goes here + from linked list addr in reg 0x0c, firmware must push through or + something. + 0xe0 - first (and only) read linked list reg, for pci memory addr + 0xe4 - first (and only) read linked list reg, for Decoder memory addr + 0xe8 - first (and only) read linked list reg, for length of buffer + 0xec-0xff - Nothing seems to be in these registers, 0xec-f4 are 0x00000000. + +Memory locations for Encoder Buffers 0x700-0x7ff: + +These registers show offsets of memory locations pertaining to each +buffer area used for encoding, have to shift them by <<1 first. + +- 0x07F8: Encoder SDRAM refresh +- 0x07FC: Encoder SDRAM pre-charge + +Memory locations for Decoder Buffers 0x800-0x8ff: + +These registers show offsets of memory locations pertaining to each +buffer area used for decoding, have to shift them by <<1 first. + +- 0x08F8: Decoder SDRAM refresh +- 0x08FC: Decoder SDRAM pre-charge + +Other memory locations: + +- 0x2800: Video Display Module control +- 0x2D00: AO (audio output?) control +- 0x2D24: Bytes Flushed +- 0x7000: LSB I2C write clock bit (inverted) +- 0x7004: LSB I2C write data bit (inverted) +- 0x7008: LSB I2C read clock bit +- 0x700c: LSB I2C read data bit +- 0x9008: GPIO get input state +- 0x900c: GPIO set output state +- 0x9020: GPIO direction (Bit7 (GPIO 0..7) - 0:input, 1:output) +- 0x9050: SPU control +- 0x9054: Reset HW blocks +- 0x9058: VPU control +- 0xA018: Bit6: interrupt pending? +- 0xA064: APU command + + +Interrupt Status Register +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The definition of the bits in the interrupt status register 0x0040, and the +interrupt mask 0x0048. If a bit is cleared in the mask, then we want our ISR to +execute. + +- bit 31 Encoder Start Capture +- bit 30 Encoder EOS +- bit 29 Encoder VBI capture +- bit 28 Encoder Video Input Module reset event +- bit 27 Encoder DMA complete +- bit 24 Decoder audio mode change detection event (through event notification) +- bit 22 Decoder data request +- bit 20 Decoder DMA complete +- bit 19 Decoder VBI re-insertion +- bit 18 Decoder DMA err (linked-list bad) + +Missing documentation +--------------------- + +- Encoder API post(?) +- Decoder API post(?) +- Decoder VTRACE event + + +The cx2341x firmware upload +--------------------------- + +This document describes how to upload the cx2341x firmware to the card. + +How to find +~~~~~~~~~~~ + +See the web pages of the various projects that uses this chip for information +on how to obtain the firmware. + +The firmware stored in a Windows driver can be detected as follows: + +- Each firmware image is 256k bytes. +- The 1st 32-bit word of the Encoder image is 0x0000da7 +- The 1st 32-bit word of the Decoder image is 0x00003a7 +- The 2nd 32-bit word of both images is 0xaa55bb66 + +How to load +~~~~~~~~~~~ + +- Issue the FWapi command to stop the encoder if it is running. Wait for the + command to complete. +- Issue the FWapi command to stop the decoder if it is running. Wait for the + command to complete. +- Issue the I2C command to the digitizer to stop emitting VSYNC events. +- Issue the FWapi command to halt the encoder's firmware. +- Sleep for 10ms. +- Issue the FWapi command to halt the decoder's firmware. +- Sleep for 10ms. +- Write 0x00000000 to register 0x2800 to stop the Video Display Module. +- Write 0x00000005 to register 0x2D00 to stop the AO (audio output?). +- Write 0x00000000 to register 0xA064 to ping? the APU. +- Write 0xFFFFFFFE to register 0x9058 to stop the VPU. +- Write 0xFFFFFFFF to register 0x9054 to reset the HW blocks. +- Write 0x00000001 to register 0x9050 to stop the SPU. +- Sleep for 10ms. +- Write 0x0000001A to register 0x07FC to init the Encoder SDRAM's pre-charge. +- Write 0x80000640 to register 0x07F8 to init the Encoder SDRAM's refresh to 1us. +- Write 0x0000001A to register 0x08FC to init the Decoder SDRAM's pre-charge. +- Write 0x80000640 to register 0x08F8 to init the Decoder SDRAM's refresh to 1us. +- Sleep for 512ms. (600ms is recommended) +- Transfer the encoder's firmware image to offset 0 in Encoder memory space. +- Transfer the decoder's firmware image to offset 0 in Decoder memory space. +- Use a read-modify-write operation to Clear bit 0 of register 0x9050 to + re-enable the SPU. +- Sleep for 1 second. +- Use a read-modify-write operation to Clear bits 3 and 0 of register 0x9058 + to re-enable the VPU. +- Sleep for 1 second. +- Issue status API commands to both firmware images to verify. + + +How to call the firmware API +---------------------------- + +The preferred calling convention is known as the firmware mailbox. The +mailboxes are basically a fixed length array that serves as the call-stack. + +Firmware mailboxes can be located by searching the encoder and decoder memory +for a 16 byte signature. That signature will be located on a 256-byte boundary. + +Signature: + +.. code-block:: none + + 0x78, 0x56, 0x34, 0x12, 0x12, 0x78, 0x56, 0x34, + 0x34, 0x12, 0x78, 0x56, 0x56, 0x34, 0x12, 0x78 + +The firmware implements 20 mailboxes of 20 32-bit words. The first 10 are +reserved for API calls. The second 10 are used by the firmware for event +notification. + + ====== ================= + Index Name + ====== ================= + 0 Flags + 1 Command + 2 Return value + 3 Timeout + 4-19 Parameter/Result + ====== ================= + + +The flags are defined in the following table. The direction is from the +perspective of the firmware. + + ==== ========== ============================================ + Bit Direction Purpose + ==== ========== ============================================ + 2 O Firmware has processed the command. + 1 I Driver has finished setting the parameters. + 0 I Driver is using this mailbox. + ==== ========== ============================================ + +The command is a 32-bit enumerator. The API specifics may be found in this +chapter. + +The return value is a 32-bit enumerator. Only two values are currently defined: + +- 0=success +- -1=command undefined. + +There are 16 parameters/results 32-bit fields. The driver populates these fields +with values for all the parameters required by the call. The driver overwrites +these fields with result values returned by the call. + +The timeout value protects the card from a hung driver thread. If the driver +doesn't handle the completed call within the timeout specified, the firmware +will reset that mailbox. + +To make an API call, the driver iterates over each mailbox looking for the +first one available (bit 0 has been cleared). The driver sets that bit, fills +in the command enumerator, the timeout value and any required parameters. The +driver then sets the parameter ready bit (bit 1). The firmware scans the +mailboxes for pending commands, processes them, sets the result code, populates +the result value array with that call's return values and sets the call +complete bit (bit 2). Once bit 2 is set, the driver should retrieve the results +and clear all the flags. If the driver does not perform this task within the +time set in the timeout register, the firmware will reset that mailbox. + +Event notifications are sent from the firmware to the host. The host tells the +firmware which events it is interested in via an API call. That call tells the +firmware which notification mailbox to use. The firmware signals the host via +an interrupt. Only the 16 Results fields are used, the Flags, Command, Return +value and Timeout words are not used. + + +OSD firmware API description +---------------------------- + +.. note:: this API is part of the decoder firmware, so it's cx23415 only. + + + +CX2341X_OSD_GET_FRAMEBUFFER +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 65/0x41 + +Description +^^^^^^^^^^^ + +Return base and length of contiguous OSD memory. + +Result[0] +^^^^^^^^^ + +OSD base address + +Result[1] +^^^^^^^^^ + +OSD length + + + +CX2341X_OSD_GET_PIXEL_FORMAT +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 66/0x42 + +Description +^^^^^^^^^^^ + +Query OSD format + +Result[0] +^^^^^^^^^ + +0=8bit index +1=16bit RGB 5:6:5 +2=16bit ARGB 1:5:5:5 +3=16bit ARGB 1:4:4:4 +4=32bit ARGB 8:8:8:8 + + + +CX2341X_OSD_SET_PIXEL_FORMAT +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 67/0x43 + +Description +^^^^^^^^^^^ + +Assign pixel format + +Param[0] +^^^^^^^^ + +- 0=8bit index +- 1=16bit RGB 5:6:5 +- 2=16bit ARGB 1:5:5:5 +- 3=16bit ARGB 1:4:4:4 +- 4=32bit ARGB 8:8:8:8 + + + +CX2341X_OSD_GET_STATE +~~~~~~~~~~~~~~~~~~~~~ + +Enum: 68/0x44 + +Description +^^^^^^^^^^^ + +Query OSD state + +Result[0] +^^^^^^^^^ + +- Bit 0 0=off, 1=on +- Bits 1:2 alpha control +- Bits 3:5 pixel format + + + +CX2341X_OSD_SET_STATE +~~~~~~~~~~~~~~~~~~~~~ + +Enum: 69/0x45 + +Description +^^^^^^^^^^^ + +OSD switch + +Param[0] +^^^^^^^^ + +0=off, 1=on + + + +CX2341X_OSD_GET_OSD_COORDS +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 70/0x46 + +Description +^^^^^^^^^^^ + +Retrieve coordinates of OSD area blended with video + +Result[0] +^^^^^^^^^ + +OSD buffer address + +Result[1] +^^^^^^^^^ + +Stride in pixels + +Result[2] +^^^^^^^^^ + +Lines in OSD buffer + +Result[3] +^^^^^^^^^ + +Horizontal offset in buffer + +Result[4] +^^^^^^^^^ + +Vertical offset in buffer + + + +CX2341X_OSD_SET_OSD_COORDS +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 71/0x47 + +Description +^^^^^^^^^^^ + +Assign the coordinates of the OSD area to blend with video + +Param[0] +^^^^^^^^ + +buffer address + +Param[1] +^^^^^^^^ + +buffer stride in pixels + +Param[2] +^^^^^^^^ + +lines in buffer + +Param[3] +^^^^^^^^ + +horizontal offset + +Param[4] +^^^^^^^^ + +vertical offset + + + +CX2341X_OSD_GET_SCREEN_COORDS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 72/0x48 + +Description +^^^^^^^^^^^ + +Retrieve OSD screen area coordinates + +Result[0] +^^^^^^^^^ + +top left horizontal offset + +Result[1] +^^^^^^^^^ + +top left vertical offset + +Result[2] +^^^^^^^^^ + +bottom right horizontal offset + +Result[3] +^^^^^^^^^ + +bottom right vertical offset + + + +CX2341X_OSD_SET_SCREEN_COORDS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 73/0x49 + +Description +^^^^^^^^^^^ + +Assign the coordinates of the screen area to blend with video + +Param[0] +^^^^^^^^ + +top left horizontal offset + +Param[1] +^^^^^^^^ + +top left vertical offset + +Param[2] +^^^^^^^^ + +bottom left horizontal offset + +Param[3] +^^^^^^^^ + +bottom left vertical offset + + + +CX2341X_OSD_GET_GLOBAL_ALPHA +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 74/0x4A + +Description +^^^^^^^^^^^ + +Retrieve OSD global alpha + +Result[0] +^^^^^^^^^ + +global alpha: 0=off, 1=on + +Result[1] +^^^^^^^^^ + +bits 0:7 global alpha + + + +CX2341X_OSD_SET_GLOBAL_ALPHA +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 75/0x4B + +Description +^^^^^^^^^^^ + +Update global alpha + +Param[0] +^^^^^^^^ + +global alpha: 0=off, 1=on + +Param[1] +^^^^^^^^ + +global alpha (8 bits) + +Param[2] +^^^^^^^^ + +local alpha: 0=on, 1=off + + + +CX2341X_OSD_SET_BLEND_COORDS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 78/0x4C + +Description +^^^^^^^^^^^ + +Move start of blending area within display buffer + +Param[0] +^^^^^^^^ + +horizontal offset in buffer + +Param[1] +^^^^^^^^ + +vertical offset in buffer + + + +CX2341X_OSD_GET_FLICKER_STATE +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 79/0x4F + +Description +^^^^^^^^^^^ + +Retrieve flicker reduction module state + +Result[0] +^^^^^^^^^ + +flicker state: 0=off, 1=on + + + +CX2341X_OSD_SET_FLICKER_STATE +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 80/0x50 + +Description +^^^^^^^^^^^ + +Set flicker reduction module state + +Param[0] +^^^^^^^^ + +State: 0=off, 1=on + + + +CX2341X_OSD_BLT_COPY +~~~~~~~~~~~~~~~~~~~~ + +Enum: 82/0x52 + +Description +^^^^^^^^^^^ + +BLT copy + +Param[0] +^^^^^^^^ + +.. code-block:: none + + '0000' zero + '0001' ~destination AND ~source + '0010' ~destination AND source + '0011' ~destination + '0100' destination AND ~source + '0101' ~source + '0110' destination XOR source + '0111' ~destination OR ~source + '1000' ~destination AND ~source + '1001' destination XNOR source + '1010' source + '1011' ~destination OR source + '1100' destination + '1101' destination OR ~source + '1110' destination OR source + '1111' one + + +Param[1] +^^^^^^^^ + +Resulting alpha blending + +- '01' source_alpha +- '10' destination_alpha +- '11' source_alpha*destination_alpha+1 + (zero if both source and destination alpha are zero) + +Param[2] +^^^^^^^^ + +.. code-block:: none + + '00' output_pixel = source_pixel + + '01' if source_alpha=0: + output_pixel = destination_pixel + if 256 > source_alpha > 1: + output_pixel = ((source_alpha + 1)*source_pixel + + (255 - source_alpha)*destination_pixel)/256 + + '10' if destination_alpha=0: + output_pixel = source_pixel + if 255 > destination_alpha > 0: + output_pixel = ((255 - destination_alpha)*source_pixel + + (destination_alpha + 1)*destination_pixel)/256 + + '11' if source_alpha=0: + source_temp = 0 + if source_alpha=255: + source_temp = source_pixel*256 + if 255 > source_alpha > 0: + source_temp = source_pixel*(source_alpha + 1) + if destination_alpha=0: + destination_temp = 0 + if destination_alpha=255: + destination_temp = destination_pixel*256 + if 255 > destination_alpha > 0: + destination_temp = destination_pixel*(destination_alpha + 1) + output_pixel = (source_temp + destination_temp)/256 + +Param[3] +^^^^^^^^ + +width + +Param[4] +^^^^^^^^ + +height + +Param[5] +^^^^^^^^ + +destination pixel mask + +Param[6] +^^^^^^^^ + +destination rectangle start address + +Param[7] +^^^^^^^^ + +destination stride in dwords + +Param[8] +^^^^^^^^ + +source stride in dwords + +Param[9] +^^^^^^^^ + +source rectangle start address + + + +CX2341X_OSD_BLT_FILL +~~~~~~~~~~~~~~~~~~~~ + +Enum: 83/0x53 + +Description +^^^^^^^^^^^ + +BLT fill color + +Param[0] +^^^^^^^^ + +Same as Param[0] on API 0x52 + +Param[1] +^^^^^^^^ + +Same as Param[1] on API 0x52 + +Param[2] +^^^^^^^^ + +Same as Param[2] on API 0x52 + +Param[3] +^^^^^^^^ + +width + +Param[4] +^^^^^^^^ + +height + +Param[5] +^^^^^^^^ + +destination pixel mask + +Param[6] +^^^^^^^^ + +destination rectangle start address + +Param[7] +^^^^^^^^ + +destination stride in dwords + +Param[8] +^^^^^^^^ + +color fill value + + + +CX2341X_OSD_BLT_TEXT +~~~~~~~~~~~~~~~~~~~~ + +Enum: 84/0x54 + +Description +^^^^^^^^^^^ + +BLT for 8 bit alpha text source + +Param[0] +^^^^^^^^ + +Same as Param[0] on API 0x52 + +Param[1] +^^^^^^^^ + +Same as Param[1] on API 0x52 + +Param[2] +^^^^^^^^ + +Same as Param[2] on API 0x52 + +Param[3] +^^^^^^^^ + +width + +Param[4] +^^^^^^^^ + +height + +Param[5] +^^^^^^^^ + +destination pixel mask + +Param[6] +^^^^^^^^ + +destination rectangle start address + +Param[7] +^^^^^^^^ + +destination stride in dwords + +Param[8] +^^^^^^^^ + +source stride in dwords + +Param[9] +^^^^^^^^ + +source rectangle start address + +Param[10] +^^^^^^^^^ + +color fill value + + + +CX2341X_OSD_SET_FRAMEBUFFER_WINDOW +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 86/0x56 + +Description +^^^^^^^^^^^ + +Positions the main output window on the screen. The coordinates must be +such that the entire window fits on the screen. + +Param[0] +^^^^^^^^ + +window width + +Param[1] +^^^^^^^^ + +window height + +Param[2] +^^^^^^^^ + +top left window corner horizontal offset + +Param[3] +^^^^^^^^ + +top left window corner vertical offset + + + +CX2341X_OSD_SET_CHROMA_KEY +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 96/0x60 + +Description +^^^^^^^^^^^ + +Chroma key switch and color + +Param[0] +^^^^^^^^ + +state: 0=off, 1=on + +Param[1] +^^^^^^^^ + +color + + + +CX2341X_OSD_GET_ALPHA_CONTENT_INDEX +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 97/0x61 + +Description +^^^^^^^^^^^ + +Retrieve alpha content index + +Result[0] +^^^^^^^^^ + +alpha content index, Range 0:15 + + + +CX2341X_OSD_SET_ALPHA_CONTENT_INDEX +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 98/0x62 + +Description +^^^^^^^^^^^ + +Assign alpha content index + +Param[0] +^^^^^^^^ + +alpha content index, range 0:15 + + +Encoder firmware API description +-------------------------------- + +CX2341X_ENC_PING_FW +~~~~~~~~~~~~~~~~~~~ + +Enum: 128/0x80 + +Description +^^^^^^^^^^^ + +Does nothing. Can be used to check if the firmware is responding. + + + +CX2341X_ENC_START_CAPTURE +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 129/0x81 + +Description +^^^^^^^^^^^ + +Commences the capture of video, audio and/or VBI data. All encoding +parameters must be initialized prior to this API call. Captures frames +continuously or until a predefined number of frames have been captured. + +Param[0] +^^^^^^^^ + +Capture stream type: + + - 0=MPEG + - 1=Raw + - 2=Raw passthrough + - 3=VBI + + +Param[1] +^^^^^^^^ + +Bitmask: + + - Bit 0 when set, captures YUV + - Bit 1 when set, captures PCM audio + - Bit 2 when set, captures VBI (same as param[0]=3) + - Bit 3 when set, the capture destination is the decoder + (same as param[0]=2) + - Bit 4 when set, the capture destination is the host + +.. note:: this parameter is only meaningful for RAW capture type. + + + +CX2341X_ENC_STOP_CAPTURE +~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 130/0x82 + +Description +^^^^^^^^^^^ + +Ends a capture in progress + +Param[0] +^^^^^^^^ + +- 0=stop at end of GOP (generates IRQ) +- 1=stop immediate (no IRQ) + +Param[1] +^^^^^^^^ + +Stream type to stop, see param[0] of API 0x81 + +Param[2] +^^^^^^^^ + +Subtype, see param[1] of API 0x81 + + + +CX2341X_ENC_SET_AUDIO_ID +~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 137/0x89 + +Description +^^^^^^^^^^^ + +Assigns the transport stream ID of the encoded audio stream + +Param[0] +^^^^^^^^ + +Audio Stream ID + + + +CX2341X_ENC_SET_VIDEO_ID +~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 139/0x8B + +Description +^^^^^^^^^^^ + +Set video transport stream ID + +Param[0] +^^^^^^^^ + +Video stream ID + + + +CX2341X_ENC_SET_PCR_ID +~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 141/0x8D + +Description +^^^^^^^^^^^ + +Assigns the transport stream ID for PCR packets + +Param[0] +^^^^^^^^ + +PCR Stream ID + + + +CX2341X_ENC_SET_FRAME_RATE +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 143/0x8F + +Description +^^^^^^^^^^^ + +Set video frames per second. Change occurs at start of new GOP. + +Param[0] +^^^^^^^^ + +- 0=30fps +- 1=25fps + + + +CX2341X_ENC_SET_FRAME_SIZE +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 145/0x91 + +Description +^^^^^^^^^^^ + +Select video stream encoding resolution. + +Param[0] +^^^^^^^^ + +Height in lines. Default 480 + +Param[1] +^^^^^^^^ + +Width in pixels. Default 720 + + + +CX2341X_ENC_SET_BIT_RATE +~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 149/0x95 + +Description +^^^^^^^^^^^ + +Assign average video stream bitrate. + +Param[0] +^^^^^^^^ + +0=variable bitrate, 1=constant bitrate + +Param[1] +^^^^^^^^ + +bitrate in bits per second + +Param[2] +^^^^^^^^ + +peak bitrate in bits per second, divided by 400 + +Param[3] +^^^^^^^^ + +Mux bitrate in bits per second, divided by 400. May be 0 (default). + +Param[4] +^^^^^^^^ + +Rate Control VBR Padding + +Param[5] +^^^^^^^^ + +VBV Buffer used by encoder + +.. note:: + + #) Param\[3\] and Param\[4\] seem to be always 0 + #) Param\[5\] doesn't seem to be used. + + + +CX2341X_ENC_SET_GOP_PROPERTIES +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 151/0x97 + +Description +^^^^^^^^^^^ + +Setup the GOP structure + +Param[0] +^^^^^^^^ + +GOP size (maximum is 34) + +Param[1] +^^^^^^^^ + +Number of B frames between the I and P frame, plus 1. +For example: IBBPBBPBBPBB --> GOP size: 12, number of B frames: 2+1 = 3 + +.. note:: + + GOP size must be a multiple of (B-frames + 1). + + + +CX2341X_ENC_SET_ASPECT_RATIO +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 153/0x99 + +Description +^^^^^^^^^^^ + +Sets the encoding aspect ratio. Changes in the aspect ratio take effect +at the start of the next GOP. + +Param[0] +^^^^^^^^ + +- '0000' forbidden +- '0001' 1:1 square +- '0010' 4:3 +- '0011' 16:9 +- '0100' 2.21:1 +- '0101' to '1111' reserved + + + +CX2341X_ENC_SET_DNR_FILTER_MODE +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 155/0x9B + +Description +^^^^^^^^^^^ + +Assign Dynamic Noise Reduction operating mode + +Param[0] +^^^^^^^^ + +Bit0: Spatial filter, set=auto, clear=manual +Bit1: Temporal filter, set=auto, clear=manual + +Param[1] +^^^^^^^^ + +Median filter: + +- 0=Disabled +- 1=Horizontal +- 2=Vertical +- 3=Horiz/Vert +- 4=Diagonal + + + +CX2341X_ENC_SET_DNR_FILTER_PROPS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 157/0x9D + +Description +^^^^^^^^^^^ + +These Dynamic Noise Reduction filter values are only meaningful when +the respective filter is set to "manual" (See API 0x9B) + +Param[0] +^^^^^^^^ + +Spatial filter: default 0, range 0:15 + +Param[1] +^^^^^^^^ + +Temporal filter: default 0, range 0:31 + + + +CX2341X_ENC_SET_CORING_LEVELS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 159/0x9F + +Description +^^^^^^^^^^^ + +Assign Dynamic Noise Reduction median filter properties. + +Param[0] +^^^^^^^^ + +Threshold above which the luminance median filter is enabled. +Default: 0, range 0:255 + +Param[1] +^^^^^^^^ + +Threshold below which the luminance median filter is enabled. +Default: 255, range 0:255 + +Param[2] +^^^^^^^^ + +Threshold above which the chrominance median filter is enabled. +Default: 0, range 0:255 + +Param[3] +^^^^^^^^ + +Threshold below which the chrominance median filter is enabled. +Default: 255, range 0:255 + + + +CX2341X_ENC_SET_SPATIAL_FILTER_TYPE +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 161/0xA1 + +Description +^^^^^^^^^^^ + +Assign spatial prefilter parameters + +Param[0] +^^^^^^^^ + +Luminance filter + +- 0=Off +- 1=1D Horizontal +- 2=1D Vertical +- 3=2D H/V Separable (default) +- 4=2D Symmetric non-separable + +Param[1] +^^^^^^^^ + +Chrominance filter + +- 0=Off +- 1=1D Horizontal (default) + + + +CX2341X_ENC_SET_VBI_LINE +~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 183/0xB7 + +Description +^^^^^^^^^^^ + +Selects VBI line number. + +Param[0] +^^^^^^^^ + +- Bits 0:4 line number +- Bit 31 0=top_field, 1=bottom_field +- Bits 0:31 all set specifies "all lines" + +Param[1] +^^^^^^^^ + +VBI line information features: 0=disabled, 1=enabled + +Param[2] +^^^^^^^^ + +Slicing: 0=None, 1=Closed Caption +Almost certainly not implemented. Set to 0. + +Param[3] +^^^^^^^^ + +Luminance samples in this line. +Almost certainly not implemented. Set to 0. + +Param[4] +^^^^^^^^ + +Chrominance samples in this line +Almost certainly not implemented. Set to 0. + + + +CX2341X_ENC_SET_STREAM_TYPE +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 185/0xB9 + +Description +^^^^^^^^^^^ + +Assign stream type + +.. note:: + + Transport stream is not working in recent firmwares. + And in older firmwares the timestamps in the TS seem to be + unreliable. + +Param[0] +^^^^^^^^ + +- 0=Program stream +- 1=Transport stream +- 2=MPEG1 stream +- 3=PES A/V stream +- 5=PES Video stream +- 7=PES Audio stream +- 10=DVD stream +- 11=VCD stream +- 12=SVCD stream +- 13=DVD_S1 stream +- 14=DVD_S2 stream + + + +CX2341X_ENC_SET_OUTPUT_PORT +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 187/0xBB + +Description +^^^^^^^^^^^ + +Assign stream output port. Normally 0 when the data is copied through +the PCI bus (DMA), and 1 when the data is streamed to another chip +(pvrusb and cx88-blackbird). + +Param[0] +^^^^^^^^ + +- 0=Memory (default) +- 1=Streaming +- 2=Serial + +Param[1] +^^^^^^^^ + +Unknown, but leaving this to 0 seems to work best. Indications are that +this might have to do with USB support, although passing anything but 0 +only breaks things. + + + +CX2341X_ENC_SET_AUDIO_PROPERTIES +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 189/0xBD + +Description +^^^^^^^^^^^ + +Set audio stream properties, may be called while encoding is in progress. + +.. note:: + + All bitfields are consistent with ISO11172 documentation except + bits 2:3 which ISO docs define as: + + - '11' Layer I + - '10' Layer II + - '01' Layer III + - '00' Undefined + + This discrepancy may indicate a possible error in the documentation. + Testing indicated that only Layer II is actually working, and that + the minimum bitrate should be 192 kbps. + +Param[0] +^^^^^^^^ + +Bitmask: + +.. code-block:: none + + 0:1 '00' 44.1Khz + '01' 48Khz + '10' 32Khz + '11' reserved + + 2:3 '01'=Layer I + '10'=Layer II + + 4:7 Bitrate: + Index | Layer I | Layer II + ------+-------------+------------ + '0000' | free format | free format + '0001' | 32 kbit/s | 32 kbit/s + '0010' | 64 kbit/s | 48 kbit/s + '0011' | 96 kbit/s | 56 kbit/s + '0100' | 128 kbit/s | 64 kbit/s + '0101' | 160 kbit/s | 80 kbit/s + '0110' | 192 kbit/s | 96 kbit/s + '0111' | 224 kbit/s | 112 kbit/s + '1000' | 256 kbit/s | 128 kbit/s + '1001' | 288 kbit/s | 160 kbit/s + '1010' | 320 kbit/s | 192 kbit/s + '1011' | 352 kbit/s | 224 kbit/s + '1100' | 384 kbit/s | 256 kbit/s + '1101' | 416 kbit/s | 320 kbit/s + '1110' | 448 kbit/s | 384 kbit/s + + .. note:: + + For Layer II, not all combinations of total bitrate + and mode are allowed. See ISO11172-3 3-Annex B, + Table 3-B.2 + + 8:9 '00'=Stereo + '01'=JointStereo + '10'=Dual + '11'=Mono + + .. note:: + + The cx23415 cannot decode Joint Stereo properly. + + 10:11 Mode Extension used in joint_stereo mode. + In Layer I and II they indicate which subbands are in + intensity_stereo. All other subbands are coded in stereo. + '00' subbands 4-31 in intensity_stereo, bound==4 + '01' subbands 8-31 in intensity_stereo, bound==8 + '10' subbands 12-31 in intensity_stereo, bound==12 + '11' subbands 16-31 in intensity_stereo, bound==16 + + 12:13 Emphasis: + '00' None + '01' 50/15uS + '10' reserved + '11' CCITT J.17 + + 14 CRC: + '0' off + '1' on + + 15 Copyright: + '0' off + '1' on + + 16 Generation: + '0' copy + '1' original + + + +CX2341X_ENC_HALT_FW +~~~~~~~~~~~~~~~~~~~ + +Enum: 195/0xC3 + +Description +^^^^^^^^^^^ + +The firmware is halted and no further API calls are serviced until the +firmware is uploaded again. + + + +CX2341X_ENC_GET_VERSION +~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 196/0xC4 + +Description +^^^^^^^^^^^ + +Returns the version of the encoder firmware. + +Result[0] +^^^^^^^^^ + +Version bitmask: +- Bits 0:15 build +- Bits 16:23 minor +- Bits 24:31 major + + + +CX2341X_ENC_SET_GOP_CLOSURE +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 197/0xC5 + +Description +^^^^^^^^^^^ + +Assigns the GOP open/close property. + +Param[0] +^^^^^^^^ + +- 0=Open +- 1=Closed + + + +CX2341X_ENC_GET_SEQ_END +~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 198/0xC6 + +Description +^^^^^^^^^^^ + +Obtains the sequence end code of the encoder's buffer. When a capture +is started a number of interrupts are still generated, the last of +which will have Result[0] set to 1 and Result[1] will contain the size +of the buffer. + +Result[0] +^^^^^^^^^ + +State of the transfer (1 if last buffer) + +Result[1] +^^^^^^^^^ + +If Result[0] is 1, this contains the size of the last buffer, undefined +otherwise. + + + +CX2341X_ENC_SET_PGM_INDEX_INFO +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 199/0xC7 + +Description +^^^^^^^^^^^ + +Sets the Program Index Information. +The information is stored as follows: + +.. code-block:: c + + struct info { + u32 length; // Length of this frame + u32 offset_low; // Offset in the file of the + u32 offset_high; // start of this frame + u32 mask1; // Bits 0-2 are the type mask: + // 1=I, 2=P, 4=B + // 0=End of Program Index, other fields + // are invalid. + u32 pts; // The PTS of the frame + u32 mask2; // Bit 0 is bit 32 of the pts. + }; + u32 table_ptr; + struct info index[400]; + +The table_ptr is the encoder memory address in the table were +*new* entries will be written. + +.. note:: This is a ringbuffer, so the table_ptr will wraparound. + +Param[0] +^^^^^^^^ + +Picture Mask: +- 0=No index capture +- 1=I frames +- 3=I,P frames +- 7=I,P,B frames + +(Seems to be ignored, it always indexes I, P and B frames) + +Param[1] +^^^^^^^^ + +Elements requested (up to 400) + +Result[0] +^^^^^^^^^ + +Offset in the encoder memory of the start of the table. + +Result[1] +^^^^^^^^^ + +Number of allocated elements up to a maximum of Param[1] + + + +CX2341X_ENC_SET_VBI_CONFIG +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 200/0xC8 + +Description +^^^^^^^^^^^ + +Configure VBI settings + +Param[0] +^^^^^^^^ + +Bitmap: + +.. code-block:: none + + 0 Mode '0' Sliced, '1' Raw + 1:3 Insertion: + '000' insert in extension & user data + '001' insert in private packets + '010' separate stream and user data + '111' separate stream and private data + 8:15 Stream ID (normally 0xBD) + +Param[1] +^^^^^^^^ + +Frames per interrupt (max 8). Only valid in raw mode. + +Param[2] +^^^^^^^^ + +Total raw VBI frames. Only valid in raw mode. + +Param[3] +^^^^^^^^ + +Start codes + +Param[4] +^^^^^^^^ + +Stop codes + +Param[5] +^^^^^^^^ + +Lines per frame + +Param[6] +^^^^^^^^ + +Byte per line + +Result[0] +^^^^^^^^^ + +Observed frames per interrupt in raw mode only. Rage 1 to Param[1] + +Result[1] +^^^^^^^^^ + +Observed number of frames in raw mode. Range 1 to Param[2] + +Result[2] +^^^^^^^^^ + +Memory offset to start or raw VBI data + + + +CX2341X_ENC_SET_DMA_BLOCK_SIZE +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 201/0xC9 + +Description +^^^^^^^^^^^ + +Set DMA transfer block size + +Param[0] +^^^^^^^^ + +DMA transfer block size in bytes or frames. When unit is bytes, +supported block sizes are 2^7, 2^8 and 2^9 bytes. + +Param[1] +^^^^^^^^ + +Unit: 0=bytes, 1=frames + + + +CX2341X_ENC_GET_PREV_DMA_INFO_MB_10 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 202/0xCA + +Description +^^^^^^^^^^^ + +Returns information on the previous DMA transfer in conjunction with +bit 27 of the interrupt mask. Uses mailbox 10. + +Result[0] +^^^^^^^^^ + +Type of stream + +Result[1] +^^^^^^^^^ + +Address Offset + +Result[2] +^^^^^^^^^ + +Maximum size of transfer + + + +CX2341X_ENC_GET_PREV_DMA_INFO_MB_9 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 203/0xCB + +Description +^^^^^^^^^^^ + +Returns information on the previous DMA transfer in conjunction with +bit 27 or 18 of the interrupt mask. Uses mailbox 9. + +Result[0] +^^^^^^^^^ + +Status bits: +- 0 read completed +- 1 write completed +- 2 DMA read error +- 3 DMA write error +- 4 Scatter-Gather array error + +Result[1] +^^^^^^^^^ + +DMA type + +Result[2] +^^^^^^^^^ + +Presentation Time Stamp bits 0..31 + +Result[3] +^^^^^^^^^ + +Presentation Time Stamp bit 32 + + + +CX2341X_ENC_SCHED_DMA_TO_HOST +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 204/0xCC + +Description +^^^^^^^^^^^ + +Setup DMA to host operation + +Param[0] +^^^^^^^^ + +Memory address of link list + +Param[1] +^^^^^^^^ + +Length of link list (wtf: what units ???) + +Param[2] +^^^^^^^^ + +DMA type (0=MPEG) + + + +CX2341X_ENC_INITIALIZE_INPUT +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 205/0xCD + +Description +^^^^^^^^^^^ + +Initializes the video input + + + +CX2341X_ENC_SET_FRAME_DROP_RATE +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 208/0xD0 + +Description +^^^^^^^^^^^ + +For each frame captured, skip specified number of frames. + +Param[0] +^^^^^^^^ + +Number of frames to skip + + + +CX2341X_ENC_PAUSE_ENCODER +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 210/0xD2 + +Description +^^^^^^^^^^^ + +During a pause condition, all frames are dropped instead of being encoded. + +Param[0] +^^^^^^^^ + +- 0=Pause encoding +- 1=Continue encoding + + + +CX2341X_ENC_REFRESH_INPUT +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 211/0xD3 + +Description +^^^^^^^^^^^ + +Refreshes the video input + + + +CX2341X_ENC_SET_COPYRIGHT +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 212/0xD4 + +Description +^^^^^^^^^^^ + +Sets stream copyright property + +Param[0] +^^^^^^^^ + + +- 0=Stream is not copyrighted +- 1=Stream is copyrighted + + + +CX2341X_ENC_SET_EVENT_NOTIFICATION +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 213/0xD5 + +Description +^^^^^^^^^^^ + +Setup firmware to notify the host about a particular event. Host must +unmask the interrupt bit. + +Param[0] +^^^^^^^^ + +Event (0=refresh encoder input) + +Param[1] +^^^^^^^^ + +Notification 0=disabled 1=enabled + +Param[2] +^^^^^^^^ + +Interrupt bit + +Param[3] +^^^^^^^^ + +Mailbox slot, -1 if no mailbox required. + + + +CX2341X_ENC_SET_NUM_VSYNC_LINES +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 214/0xD6 + +Description +^^^^^^^^^^^ + +Depending on the analog video decoder used, this assigns the number +of lines for field 1 and 2. + +Param[0] +^^^^^^^^ + +Field 1 number of lines: +- 0x00EF for SAA7114 +- 0x00F0 for SAA7115 +- 0x0105 for Micronas + +Param[1] +^^^^^^^^ + +Field 2 number of lines: +- 0x00EF for SAA7114 +- 0x00F0 for SAA7115 +- 0x0106 for Micronas + + + +CX2341X_ENC_SET_PLACEHOLDER +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 215/0xD7 + +Description +^^^^^^^^^^^ + +Provides a mechanism of inserting custom user data in the MPEG stream. + +Param[0] +^^^^^^^^ + +- 0=extension & user data +- 1=private packet with stream ID 0xBD + +Param[1] +^^^^^^^^ + +Rate at which to insert data, in units of frames (for private packet) +or GOPs (for ext. & user data) + +Param[2] +^^^^^^^^ + +Number of data DWORDs (below) to insert + +Param[3] +^^^^^^^^ + +Custom data 0 + +Param[4] +^^^^^^^^ + +Custom data 1 + +Param[5] +^^^^^^^^ + +Custom data 2 + +Param[6] +^^^^^^^^ + +Custom data 3 + +Param[7] +^^^^^^^^ + +Custom data 4 + +Param[8] +^^^^^^^^ + +Custom data 5 + +Param[9] +^^^^^^^^ + +Custom data 6 + +Param[10] +^^^^^^^^^ + +Custom data 7 + +Param[11] +^^^^^^^^^ + +Custom data 8 + + + +CX2341X_ENC_MUTE_VIDEO +~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 217/0xD9 + +Description +^^^^^^^^^^^ + +Video muting + +Param[0] +^^^^^^^^ + +Bit usage: + +.. code-block:: none + + 0 '0'=video not muted + '1'=video muted, creates frames with the YUV color defined below + 1:7 Unused + 8:15 V chrominance information + 16:23 U chrominance information + 24:31 Y luminance information + + + +CX2341X_ENC_MUTE_AUDIO +~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 218/0xDA + +Description +^^^^^^^^^^^ + +Audio muting + +Param[0] +^^^^^^^^ + +- 0=audio not muted +- 1=audio muted (produces silent mpeg audio stream) + + + +CX2341X_ENC_SET_VERT_CROP_LINE +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 219/0xDB + +Description +^^^^^^^^^^^ + +Something to do with 'Vertical Crop Line' + +Param[0] +^^^^^^^^ + +If saa7114 and raw VBI capture and 60 Hz, then set to 10001. +Else 0. + + + +CX2341X_ENC_MISC +~~~~~~~~~~~~~~~~ + +Enum: 220/0xDC + +Description +^^^^^^^^^^^ + +Miscellaneous actions. Not known for 100% what it does. It's really a +sort of ioctl call. The first parameter is a command number, the second +the value. + +Param[0] +^^^^^^^^ + +Command number: + +.. code-block:: none + + 1=set initial SCR value when starting encoding (works). + 2=set quality mode (apparently some test setting). + 3=setup advanced VIM protection handling. + Always 1 for the cx23416 and 0 for cx23415. + 4=generate DVD compatible PTS timestamps + 5=USB flush mode + 6=something to do with the quantization matrix + 7=set navigation pack insertion for DVD: adds 0xbf (private stream 2) + packets to the MPEG. The size of these packets is 2048 bytes (including + the header of 6 bytes: 0x000001bf + length). The payload is zeroed and + it is up to the application to fill them in. These packets are apparently + inserted every four frames. + 8=enable scene change detection (seems to be a failure) + 9=set history parameters of the video input module + 10=set input field order of VIM + 11=set quantization matrix + 12=reset audio interface after channel change or input switch (has no argument). + Needed for the cx2584x, not needed for the mspx4xx, but it doesn't seem to + do any harm calling it regardless. + 13=set audio volume delay + 14=set audio delay + + +Param[1] +^^^^^^^^ + +Command value. + +Decoder firmware API description +-------------------------------- + +.. note:: this API is part of the decoder firmware, so it's cx23415 only. + + + +CX2341X_DEC_PING_FW +~~~~~~~~~~~~~~~~~~~ + +Enum: 0/0x00 + +Description +^^^^^^^^^^^ + +This API call does nothing. It may be used to check if the firmware +is responding. + + + +CX2341X_DEC_START_PLAYBACK +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 1/0x01 + +Description +^^^^^^^^^^^ + +Begin or resume playback. + +Param[0] +^^^^^^^^ + +0 based frame number in GOP to begin playback from. + +Param[1] +^^^^^^^^ + +Specifies the number of muted audio frames to play before normal +audio resumes. (This is not implemented in the firmware, leave at 0) + + + +CX2341X_DEC_STOP_PLAYBACK +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 2/0x02 + +Description +^^^^^^^^^^^ + +Ends playback and clears all decoder buffers. If PTS is not zero, +playback stops at specified PTS. + +Param[0] +^^^^^^^^ + +Display 0=last frame, 1=black + +.. note:: + + this takes effect immediately, so if you want to wait for a PTS, + then use '0', otherwise the screen goes to black at once. + You can call this later (even if there is no playback) with a 1 value + to set the screen to black. + +Param[1] +^^^^^^^^ + +PTS low + +Param[2] +^^^^^^^^ + +PTS high + + + +CX2341X_DEC_SET_PLAYBACK_SPEED +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 3/0x03 + +Description +^^^^^^^^^^^ + +Playback stream at speed other than normal. There are two modes of +operation: + + - Smooth: host transfers entire stream and firmware drops unused + frames. + - Coarse: host drops frames based on indexing as required to achieve + desired speed. + +Param[0] +^^^^^^^^ + +.. code-block:: none + + Bitmap: + 0:7 0 normal + 1 fast only "1.5 times" + n nX fast, 1/nX slow + 30 Framedrop: + '0' during 1.5 times play, every other B frame is dropped + '1' during 1.5 times play, stream is unchanged (bitrate + must not exceed 8mbps) + 31 Speed: + '0' slow + '1' fast + +.. note:: + + n is limited to 2. Anything higher does not result in + faster playback. Instead the host should start dropping frames. + +Param[1] +^^^^^^^^ + +Direction: 0=forward, 1=reverse + +.. note:: + + to make reverse playback work you have to write full GOPs in + reverse order. + +Param[2] +^^^^^^^^ + +.. code-block:: none + + Picture mask: + 1=I frames + 3=I, P frames + 7=I, P, B frames + +Param[3] +^^^^^^^^ + +B frames per GOP (for reverse play only) + +.. note:: + + for reverse playback the Picture Mask should be set to I or I, P. + Adding B frames to the mask will result in corrupt video. This field + has to be set to the correct value in order to keep the timing correct. + +Param[4] +^^^^^^^^ + +Mute audio: 0=disable, 1=enable + +Param[5] +^^^^^^^^ + +Display 0=frame, 1=field + +Param[6] +^^^^^^^^ + +Specifies the number of muted audio frames to play before normal audio +resumes. (Not implemented in the firmware, leave at 0) + + + +CX2341X_DEC_STEP_VIDEO +~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 5/0x05 + +Description +^^^^^^^^^^^ + +Each call to this API steps the playback to the next unit defined below +in the current playback direction. + +Param[0] +^^^^^^^^ + +0=frame, 1=top field, 2=bottom field + + + +CX2341X_DEC_SET_DMA_BLOCK_SIZE +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 8/0x08 + +Description +^^^^^^^^^^^ + +Set DMA transfer block size. Counterpart to API 0xC9 + +Param[0] +^^^^^^^^ + +DMA transfer block size in bytes. A different size may be specified +when issuing the DMA transfer command. + + + +CX2341X_DEC_GET_XFER_INFO +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 9/0x09 + +Description +^^^^^^^^^^^ + +This API call may be used to detect an end of stream condition. + +Result[0] +^^^^^^^^^ + +Stream type + +Result[1] +^^^^^^^^^ + +Address offset + +Result[2] +^^^^^^^^^ + +Maximum bytes to transfer + +Result[3] +^^^^^^^^^ + +Buffer fullness + + + +CX2341X_DEC_GET_DMA_STATUS +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 10/0x0A + +Description +^^^^^^^^^^^ + +Status of the last DMA transfer + +Result[0] +^^^^^^^^^ + +Bit 1 set means transfer complete +Bit 2 set means DMA error +Bit 3 set means linked list error + +Result[1] +^^^^^^^^^ + +DMA type: 0=MPEG, 1=OSD, 2=YUV + + + +CX2341X_DEC_SCHED_DMA_FROM_HOST +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 11/0x0B + +Description +^^^^^^^^^^^ + +Setup DMA from host operation. Counterpart to API 0xCC + +Param[0] +^^^^^^^^ + +Memory address of link list + +Param[1] +^^^^^^^^ + +Total # of bytes to transfer + +Param[2] +^^^^^^^^ + +DMA type (0=MPEG, 1=OSD, 2=YUV) + + + +CX2341X_DEC_PAUSE_PLAYBACK +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 13/0x0D + +Description +^^^^^^^^^^^ + +Freeze playback immediately. In this mode, when internal buffers are +full, no more data will be accepted and data request IRQs will be +masked. + +Param[0] +^^^^^^^^ + +Display: 0=last frame, 1=black + + + +CX2341X_DEC_HALT_FW +~~~~~~~~~~~~~~~~~~~ + +Enum: 14/0x0E + +Description +^^^^^^^^^^^ + +The firmware is halted and no further API calls are serviced until +the firmware is uploaded again. + + + +CX2341X_DEC_SET_STANDARD +~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 16/0x10 + +Description +^^^^^^^^^^^ + +Selects display standard + +Param[0] +^^^^^^^^ + +0=NTSC, 1=PAL + + + +CX2341X_DEC_GET_VERSION +~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 17/0x11 + +Description +^^^^^^^^^^^ + +Returns decoder firmware version information + +Result[0] +^^^^^^^^^ + +Version bitmask: + - Bits 0:15 build + - Bits 16:23 minor + - Bits 24:31 major + + + +CX2341X_DEC_SET_STREAM_INPUT +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 20/0x14 + +Description +^^^^^^^^^^^ + +Select decoder stream input port + +Param[0] +^^^^^^^^ + +0=memory (default), 1=streaming + + + +CX2341X_DEC_GET_TIMING_INFO +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 21/0x15 + +Description +^^^^^^^^^^^ + +Returns timing information from start of playback + +Result[0] +^^^^^^^^^ + +Frame count by decode order + +Result[1] +^^^^^^^^^ + +Video PTS bits 0:31 by display order + +Result[2] +^^^^^^^^^ + +Video PTS bit 32 by display order + +Result[3] +^^^^^^^^^ + +SCR bits 0:31 by display order + +Result[4] +^^^^^^^^^ + +SCR bit 32 by display order + + + +CX2341X_DEC_SET_AUDIO_MODE +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 22/0x16 + +Description +^^^^^^^^^^^ + +Select audio mode + +Param[0] +^^^^^^^^ + +Dual mono mode action + 0=Stereo, 1=Left, 2=Right, 3=Mono, 4=Swap, -1=Unchanged + +Param[1] +^^^^^^^^ + +Stereo mode action: + 0=Stereo, 1=Left, 2=Right, 3=Mono, 4=Swap, -1=Unchanged + + + +CX2341X_DEC_SET_EVENT_NOTIFICATION +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 23/0x17 + +Description +^^^^^^^^^^^ + +Setup firmware to notify the host about a particular event. +Counterpart to API 0xD5 + +Param[0] +^^^^^^^^ + +Event: + - 0=Audio mode change between mono, (joint) stereo and dual channel. + - 3=Decoder started + - 4=Unknown: goes off 10-15 times per second while decoding. + - 5=Some sync event: goes off once per frame. + +Param[1] +^^^^^^^^ + +Notification 0=disabled, 1=enabled + +Param[2] +^^^^^^^^ + +Interrupt bit + +Param[3] +^^^^^^^^ + +Mailbox slot, -1 if no mailbox required. + + + +CX2341X_DEC_SET_DISPLAY_BUFFERS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 24/0x18 + +Description +^^^^^^^^^^^ + +Number of display buffers. To decode all frames in reverse playback you +must use nine buffers. + +Param[0] +^^^^^^^^ + +0=six buffers, 1=nine buffers + + + +CX2341X_DEC_EXTRACT_VBI +~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 25/0x19 + +Description +^^^^^^^^^^^ + +Extracts VBI data + +Param[0] +^^^^^^^^ + +0=extract from extension & user data, 1=extract from private packets + +Result[0] +^^^^^^^^^ + +VBI table location + +Result[1] +^^^^^^^^^ + +VBI table size + + + +CX2341X_DEC_SET_DECODER_SOURCE +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 26/0x1A + +Description +^^^^^^^^^^^ + +Selects decoder source. Ensure that the parameters passed to this +API match the encoder settings. + +Param[0] +^^^^^^^^ + +Mode: 0=MPEG from host, 1=YUV from encoder, 2=YUV from host + +Param[1] +^^^^^^^^ + +YUV picture width + +Param[2] +^^^^^^^^ + +YUV picture height + +Param[3] +^^^^^^^^ + +Bitmap: see Param[0] of API 0xBD + + + +CX2341X_DEC_SET_PREBUFFERING +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 30/0x1E + +Description +^^^^^^^^^^^ + +Decoder prebuffering, when enabled up to 128KB are buffered for +streams <8mpbs or 640KB for streams >8mbps + +Param[0] +^^^^^^^^ + +0=off, 1=on + +PVR350 Video decoder registers 0x02002800 -> 0x02002B00 +------------------------------------------------------- + +Author: Ian Armstrong <ian@iarmst.demon.co.uk> + +Version: v0.4 + +Date: 12 March 2007 + + +This list has been worked out through trial and error. There will be mistakes +and omissions. Some registers have no obvious effect so it's hard to say what +they do, while others interact with each other, or require a certain load +sequence. Horizontal filter setup is one example, with six registers working +in unison and requiring a certain load sequence to correctly configure. The +indexed colour palette is much easier to set at just two registers, but again +it requires a certain load sequence. + +Some registers are fussy about what they are set to. Load in a bad value & the +decoder will fail. A firmware reload will often recover, but sometimes a reset +is required. For registers containing size information, setting them to 0 is +generally a bad idea. For other control registers i.e. 2878, you'll only find +out what values are bad when it hangs. + +.. code-block:: none + + -------------------------------------------------------------------------------- + 2800 + bit 0 + Decoder enable + 0 = disable + 1 = enable + -------------------------------------------------------------------------------- + 2804 + bits 0:31 + Decoder horizontal Y alias register 1 + --------------- + 2808 + bits 0:31 + Decoder horizontal Y alias register 2 + --------------- + 280C + bits 0:31 + Decoder horizontal Y alias register 3 + --------------- + 2810 + bits 0:31 + Decoder horizontal Y alias register 4 + --------------- + 2814 + bits 0:31 + Decoder horizontal Y alias register 5 + --------------- + 2818 + bits 0:31 + Decoder horizontal Y alias trigger + + These six registers control the horizontal aliasing filter for the Y plane. + The first five registers must all be loaded before accessing the trigger + (2818), as this register actually clocks the data through for the first + five. + + To correctly program set the filter, this whole procedure must be done 16 + times. The actual register contents are copied from a lookup-table in the + firmware which contains 4 different filter settings. + + -------------------------------------------------------------------------------- + 281C + bits 0:31 + Decoder horizontal UV alias register 1 + --------------- + 2820 + bits 0:31 + Decoder horizontal UV alias register 2 + --------------- + 2824 + bits 0:31 + Decoder horizontal UV alias register 3 + --------------- + 2828 + bits 0:31 + Decoder horizontal UV alias register 4 + --------------- + 282C + bits 0:31 + Decoder horizontal UV alias register 5 + --------------- + 2830 + bits 0:31 + Decoder horizontal UV alias trigger + + These six registers control the horizontal aliasing for the UV plane. + Operation is the same as the Y filter, with 2830 being the trigger + register. + + -------------------------------------------------------------------------------- + 2834 + bits 0:15 + Decoder Y source width in pixels + + bits 16:31 + Decoder Y destination width in pixels + --------------- + 2838 + bits 0:15 + Decoder UV source width in pixels + + bits 16:31 + Decoder UV destination width in pixels + + NOTE: For both registers, the resulting image must be fully visible on + screen. If the image exceeds the right edge both the source and destination + size must be adjusted to reflect the visible portion. For the source width, + you must take into account the scaling when calculating the new value. + -------------------------------------------------------------------------------- + + 283C + bits 0:31 + Decoder Y horizontal scaling + Normally = Reg 2854 >> 2 + --------------- + 2840 + bits 0:31 + Decoder ?? unknown - horizontal scaling + Usually 0x00080514 + --------------- + 2844 + bits 0:31 + Decoder UV horizontal scaling + Normally = Reg 2854 >> 2 + --------------- + 2848 + bits 0:31 + Decoder ?? unknown - horizontal scaling + Usually 0x00100514 + --------------- + 284C + bits 0:31 + Decoder ?? unknown - Y plane + Usually 0x00200020 + --------------- + 2850 + bits 0:31 + Decoder ?? unknown - UV plane + Usually 0x00200020 + --------------- + 2854 + bits 0:31 + Decoder 'master' value for horizontal scaling + --------------- + 2858 + bits 0:31 + Decoder ?? unknown + Usually 0 + --------------- + 285C + bits 0:31 + Decoder ?? unknown + Normally = Reg 2854 >> 1 + --------------- + 2860 + bits 0:31 + Decoder ?? unknown + Usually 0 + --------------- + 2864 + bits 0:31 + Decoder ?? unknown + Normally = Reg 2854 >> 1 + --------------- + 2868 + bits 0:31 + Decoder ?? unknown + Usually 0 + + Most of these registers either control horizontal scaling, or appear linked + to it in some way. Register 2854 contains the 'master' value & the other + registers can be calculated from that one. You must also remember to + correctly set the divider in Reg 2874. + + To enlarge: + Reg 2854 = (source_width * 0x00200000) / destination_width + Reg 2874 = No divide + + To reduce from full size down to half size: + Reg 2854 = (source_width/2 * 0x00200000) / destination width + Reg 2874 = Divide by 2 + + To reduce from half size down to quarter size: + Reg 2854 = (source_width/4 * 0x00200000) / destination width + Reg 2874 = Divide by 4 + + The result is always rounded up. + + -------------------------------------------------------------------------------- + 286C + bits 0:15 + Decoder horizontal Y buffer offset + + bits 15:31 + Decoder horizontal UV buffer offset + + Offset into the video image buffer. If the offset is gradually incremented, + the on screen image will move left & wrap around higher up on the right. + + -------------------------------------------------------------------------------- + 2870 + bits 0:15 + Decoder horizontal Y output offset + + bits 16:31 + Decoder horizontal UV output offset + + Offsets the actual video output. Controls output alignment of the Y & UV + planes. The higher the value, the greater the shift to the left. Use + reg 2890 to move the image right. + + -------------------------------------------------------------------------------- + 2874 + bits 0:1 + Decoder horizontal Y output size divider + 00 = No divide + 01 = Divide by 2 + 10 = Divide by 3 + + bits 4:5 + Decoder horizontal UV output size divider + 00 = No divide + 01 = Divide by 2 + 10 = Divide by 3 + + bit 8 + Decoder ?? unknown + 0 = Normal + 1 = Affects video output levels + + bit 16 + Decoder ?? unknown + 0 = Normal + 1 = Disable horizontal filter + + -------------------------------------------------------------------------------- + 2878 + bit 0 + ?? unknown + + bit 1 + osd on/off + 0 = osd off + 1 = osd on + + bit 2 + Decoder + osd video timing + 0 = NTSC + 1 = PAL + + bits 3:4 + ?? unknown + + bit 5 + Decoder + osd + Swaps upper & lower fields + + -------------------------------------------------------------------------------- + 287C + bits 0:10 + Decoder & osd ?? unknown + Moves entire screen horizontally. Starts at 0x005 with the screen + shifted heavily to the right. Incrementing in steps of 0x004 will + gradually shift the screen to the left. + + bits 11:31 + ?? unknown + + Normally contents are 0x00101111 (NTSC) or 0x1010111d (PAL) + + -------------------------------------------------------------------------------- + 2880 -------- ?? unknown + 2884 -------- ?? unknown + -------------------------------------------------------------------------------- + 2888 + bit 0 + Decoder + osd ?? unknown + 0 = Normal + 1 = Misaligned fields (Correctable through 289C & 28A4) + + bit 4 + ?? unknown + + bit 8 + ?? unknown + + Warning: Bad values will require a firmware reload to recover. + Known to be bad are 0x000,0x011,0x100,0x111 + -------------------------------------------------------------------------------- + 288C + bits 0:15 + osd ?? unknown + Appears to affect the osd position stability. The higher the value the + more unstable it becomes. Decoder output remains stable. + + bits 16:31 + osd ?? unknown + Same as bits 0:15 + + -------------------------------------------------------------------------------- + 2890 + bits 0:11 + Decoder output horizontal offset. + + Horizontal offset moves the video image right. A small left shift is + possible, but it's better to use reg 2870 for that due to its greater + range. + + NOTE: Video corruption will occur if video window is shifted off the right + edge. To avoid this read the notes for 2834 & 2838. + -------------------------------------------------------------------------------- + 2894 + bits 0:23 + Decoder output video surround colour. + + Contains the colour (in yuv) used to fill the screen when the video is + running in a window. + -------------------------------------------------------------------------------- + 2898 + bits 0:23 + Decoder video window colour + Contains the colour (in yuv) used to fill the video window when the + video is turned off. + + bit 24 + Decoder video output + 0 = Video on + 1 = Video off + + bit 28 + Decoder plane order + 0 = Y,UV + 1 = UV,Y + + bit 29 + Decoder second plane byte order + 0 = Normal (UV) + 1 = Swapped (VU) + + In normal usage, the first plane is Y & the second plane is UV. Though the + order of the planes can be swapped, only the byte order of the second plane + can be swapped. This isn't much use for the Y plane, but can be useful for + the UV plane. + + -------------------------------------------------------------------------------- + 289C + bits 0:15 + Decoder vertical field offset 1 + + bits 16:31 + Decoder vertical field offset 2 + + Controls field output vertical alignment. The higher the number, the lower + the image on screen. Known starting values are 0x011E0017 (NTSC) & + 0x01500017 (PAL) + -------------------------------------------------------------------------------- + 28A0 + bits 0:15 + Decoder & osd width in pixels + + bits 16:31 + Decoder & osd height in pixels + + All output from the decoder & osd are disabled beyond this area. Decoder + output will simply go black outside of this region. If the osd tries to + exceed this area it will become corrupt. + -------------------------------------------------------------------------------- + 28A4 + bits 0:11 + osd left shift. + + Has a range of 0x770->0x7FF. With the exception of 0, any value outside of + this range corrupts the osd. + -------------------------------------------------------------------------------- + 28A8 + bits 0:15 + osd vertical field offset 1 + + bits 16:31 + osd vertical field offset 2 + + Controls field output vertical alignment. The higher the number, the lower + the image on screen. Known starting values are 0x011E0017 (NTSC) & + 0x01500017 (PAL) + -------------------------------------------------------------------------------- + 28AC -------- ?? unknown + | + V + 28BC -------- ?? unknown + -------------------------------------------------------------------------------- + 28C0 + bit 0 + Current output field + 0 = first field + 1 = second field + + bits 16:31 + Current scanline + The scanline counts from the top line of the first field + through to the last line of the second field. + -------------------------------------------------------------------------------- + 28C4 -------- ?? unknown + | + V + 28F8 -------- ?? unknown + -------------------------------------------------------------------------------- + 28FC + bit 0 + ?? unknown + 0 = Normal + 1 = Breaks decoder & osd output + -------------------------------------------------------------------------------- + 2900 + bits 0:31 + Decoder vertical Y alias register 1 + --------------- + 2904 + bits 0:31 + Decoder vertical Y alias register 2 + --------------- + 2908 + bits 0:31 + Decoder vertical Y alias trigger + + These three registers control the vertical aliasing filter for the Y plane. + Operation is similar to the horizontal Y filter (2804). The only real + difference is that there are only two registers to set before accessing + the trigger register (2908). As for the horizontal filter, the values are + taken from a lookup table in the firmware, and the procedure must be + repeated 16 times to fully program the filter. + -------------------------------------------------------------------------------- + 290C + bits 0:31 + Decoder vertical UV alias register 1 + --------------- + 2910 + bits 0:31 + Decoder vertical UV alias register 2 + --------------- + 2914 + bits 0:31 + Decoder vertical UV alias trigger + + These three registers control the vertical aliasing filter for the UV + plane. Operation is the same as the Y filter, with 2914 being the trigger. + -------------------------------------------------------------------------------- + 2918 + bits 0:15 + Decoder Y source height in pixels + + bits 16:31 + Decoder Y destination height in pixels + --------------- + 291C + bits 0:15 + Decoder UV source height in pixels divided by 2 + + bits 16:31 + Decoder UV destination height in pixels + + NOTE: For both registers, the resulting image must be fully visible on + screen. If the image exceeds the bottom edge both the source and + destination size must be adjusted to reflect the visible portion. For the + source height, you must take into account the scaling when calculating the + new value. + -------------------------------------------------------------------------------- + 2920 + bits 0:31 + Decoder Y vertical scaling + Normally = Reg 2930 >> 2 + --------------- + 2924 + bits 0:31 + Decoder Y vertical scaling + Normally = Reg 2920 + 0x514 + --------------- + 2928 + bits 0:31 + Decoder UV vertical scaling + When enlarging = Reg 2930 >> 2 + When reducing = Reg 2930 >> 3 + --------------- + 292C + bits 0:31 + Decoder UV vertical scaling + Normally = Reg 2928 + 0x514 + --------------- + 2930 + bits 0:31 + Decoder 'master' value for vertical scaling + --------------- + 2934 + bits 0:31 + Decoder ?? unknown - Y vertical scaling + --------------- + 2938 + bits 0:31 + Decoder Y vertical scaling + Normally = Reg 2930 + --------------- + 293C + bits 0:31 + Decoder ?? unknown - Y vertical scaling + --------------- + 2940 + bits 0:31 + Decoder UV vertical scaling + When enlarging = Reg 2930 >> 1 + When reducing = Reg 2930 + --------------- + 2944 + bits 0:31 + Decoder ?? unknown - UV vertical scaling + --------------- + 2948 + bits 0:31 + Decoder UV vertical scaling + Normally = Reg 2940 + --------------- + 294C + bits 0:31 + Decoder ?? unknown - UV vertical scaling + + Most of these registers either control vertical scaling, or appear linked + to it in some way. Register 2930 contains the 'master' value & all other + registers can be calculated from that one. You must also remember to + correctly set the divider in Reg 296C + + To enlarge: + Reg 2930 = (source_height * 0x00200000) / destination_height + Reg 296C = No divide + + To reduce from full size down to half size: + Reg 2930 = (source_height/2 * 0x00200000) / destination height + Reg 296C = Divide by 2 + + To reduce from half down to quarter. + Reg 2930 = (source_height/4 * 0x00200000) / destination height + Reg 296C = Divide by 4 + + -------------------------------------------------------------------------------- + 2950 + bits 0:15 + Decoder Y line index into display buffer, first field + + bits 16:31 + Decoder Y vertical line skip, first field + -------------------------------------------------------------------------------- + 2954 + bits 0:15 + Decoder Y line index into display buffer, second field + + bits 16:31 + Decoder Y vertical line skip, second field + -------------------------------------------------------------------------------- + 2958 + bits 0:15 + Decoder UV line index into display buffer, first field + + bits 16:31 + Decoder UV vertical line skip, first field + -------------------------------------------------------------------------------- + 295C + bits 0:15 + Decoder UV line index into display buffer, second field + + bits 16:31 + Decoder UV vertical line skip, second field + -------------------------------------------------------------------------------- + 2960 + bits 0:15 + Decoder destination height minus 1 + + bits 16:31 + Decoder destination height divided by 2 + -------------------------------------------------------------------------------- + 2964 + bits 0:15 + Decoder Y vertical offset, second field + + bits 16:31 + Decoder Y vertical offset, first field + + These two registers shift the Y plane up. The higher the number, the + greater the shift. + -------------------------------------------------------------------------------- + 2968 + bits 0:15 + Decoder UV vertical offset, second field + + bits 16:31 + Decoder UV vertical offset, first field + + These two registers shift the UV plane up. The higher the number, the + greater the shift. + -------------------------------------------------------------------------------- + 296C + bits 0:1 + Decoder vertical Y output size divider + 00 = No divide + 01 = Divide by 2 + 10 = Divide by 4 + + bits 8:9 + Decoder vertical UV output size divider + 00 = No divide + 01 = Divide by 2 + 10 = Divide by 4 + -------------------------------------------------------------------------------- + 2970 + bit 0 + Decoder ?? unknown + 0 = Normal + 1 = Affect video output levels + + bit 16 + Decoder ?? unknown + 0 = Normal + 1 = Disable vertical filter + + -------------------------------------------------------------------------------- + 2974 -------- ?? unknown + | + V + 29EF -------- ?? unknown + -------------------------------------------------------------------------------- + 2A00 + bits 0:2 + osd colour mode + 000 = 8 bit indexed + 001 = 16 bit (565) + 010 = 15 bit (555) + 011 = 12 bit (444) + 100 = 32 bit (8888) + + bits 4:5 + osd display bpp + 01 = 8 bit + 10 = 16 bit + 11 = 32 bit + + bit 8 + osd global alpha + 0 = Off + 1 = On + + bit 9 + osd local alpha + 0 = Off + 1 = On + + bit 10 + osd colour key + 0 = Off + 1 = On + + bit 11 + osd ?? unknown + Must be 1 + + bit 13 + osd colour space + 0 = ARGB + 1 = AYVU + + bits 16:31 + osd ?? unknown + Must be 0x001B (some kind of buffer pointer ?) + + When the bits-per-pixel is set to 8, the colour mode is ignored and + assumed to be 8 bit indexed. For 16 & 32 bits-per-pixel the colour depth + is honoured, and when using a colour depth that requires fewer bytes than + allocated the extra bytes are used as padding. So for a 32 bpp with 8 bit + index colour, there are 3 padding bytes per pixel. It's also possible to + select 16bpp with a 32 bit colour mode. This results in the pixel width + being doubled, but the color key will not work as expected in this mode. + + Colour key is as it suggests. You designate a colour which will become + completely transparent. When using 565, 555 or 444 colour modes, the + colour key is always 16 bits wide. The colour to key on is set in Reg 2A18. + + Local alpha works differently depending on the colour mode. For 32bpp & 8 + bit indexed, local alpha is a per-pixel 256 step transparency, with 0 being + transparent and 255 being solid. For the 16bpp modes 555 & 444, the unused + bit(s) act as a simple transparency switch, with 0 being solid & 1 being + fully transparent. There is no local alpha support for 16bit 565. + + Global alpha is a 256 step transparency that applies to the entire osd, + with 0 being transparent & 255 being solid. + + It's possible to combine colour key, local alpha & global alpha. + -------------------------------------------------------------------------------- + 2A04 + bits 0:15 + osd x coord for left edge + + bits 16:31 + osd y coord for top edge + --------------- + 2A08 + bits 0:15 + osd x coord for right edge + + bits 16:31 + osd y coord for bottom edge + + For both registers, (0,0) = top left corner of the display area. These + registers do not control the osd size, only where it's positioned & how + much is visible. The visible osd area cannot exceed the right edge of the + display, otherwise the osd will become corrupt. See reg 2A10 for + setting osd width. + -------------------------------------------------------------------------------- + 2A0C + bits 0:31 + osd buffer index + + An index into the osd buffer. Slowly incrementing this moves the osd left, + wrapping around onto the right edge + -------------------------------------------------------------------------------- + 2A10 + bits 0:11 + osd buffer 32 bit word width + + Contains the width of the osd measured in 32 bit words. This means that all + colour modes are restricted to a byte width which is divisible by 4. + -------------------------------------------------------------------------------- + 2A14 + bits 0:15 + osd height in pixels + + bits 16:32 + osd line index into buffer + osd will start displaying from this line. + -------------------------------------------------------------------------------- + 2A18 + bits 0:31 + osd colour key + + Contains the colour value which will be transparent. + -------------------------------------------------------------------------------- + 2A1C + bits 0:7 + osd global alpha + + Contains the global alpha value (equiv ivtvfbctl --alpha XX) + -------------------------------------------------------------------------------- + 2A20 -------- ?? unknown + | + V + 2A2C -------- ?? unknown + -------------------------------------------------------------------------------- + 2A30 + bits 0:7 + osd colour to change in indexed palette + --------------- + 2A34 + bits 0:31 + osd colour for indexed palette + + To set the new palette, first load the index of the colour to change into + 2A30, then load the new colour into 2A34. The full palette is 256 colours, + so the index range is 0x00-0xFF + -------------------------------------------------------------------------------- + 2A38 -------- ?? unknown + 2A3C -------- ?? unknown + -------------------------------------------------------------------------------- + 2A40 + bits 0:31 + osd ?? unknown + + Affects overall brightness, wrapping around to black + -------------------------------------------------------------------------------- + 2A44 + bits 0:31 + osd ?? unknown + + Green tint + -------------------------------------------------------------------------------- + 2A48 + bits 0:31 + osd ?? unknown + + Red tint + -------------------------------------------------------------------------------- + 2A4C + bits 0:31 + osd ?? unknown + + Affects overall brightness, wrapping around to black + -------------------------------------------------------------------------------- + 2A50 + bits 0:31 + osd ?? unknown + + Colour shift + -------------------------------------------------------------------------------- + 2A54 + bits 0:31 + osd ?? unknown + + Colour shift + -------------------------------------------------------------------------------- + 2A58 -------- ?? unknown + | + V + 2AFC -------- ?? unknown + -------------------------------------------------------------------------------- + 2B00 + bit 0 + osd filter control + 0 = filter off + 1 = filter on + + bits 1:4 + osd ?? unknown + + -------------------------------------------------------------------------------- + +The cx231xx DMA engine +---------------------- + + +This page describes the structures and procedures used by the cx2341x DMA +engine. + +Introduction +~~~~~~~~~~~~ + +The cx2341x PCI interface is busmaster capable. This means it has a DMA +engine to efficiently transfer large volumes of data between the card and main +memory without requiring help from a CPU. Like most hardware, it must operate +on contiguous physical memory. This is difficult to come by in large quantities +on virtual memory machines. + +Therefore, it also supports a technique called "scatter-gather". The card can +transfer multiple buffers in one operation. Instead of allocating one large +contiguous buffer, the driver can allocate several smaller buffers. + +In practice, I've seen the average transfer to be roughly 80K, but transfers +above 128K were not uncommon, particularly at startup. The 128K figure is +important, because that is the largest block that the kernel can normally +allocate. Even still, 128K blocks are hard to come by, so the driver writer is +urged to choose a smaller block size and learn the scatter-gather technique. + +Mailbox #10 is reserved for DMA transfer information. + +Note: the hardware expects little-endian data ('intel format'). + +Flow +~~~~ + +This section describes, in general, the order of events when handling DMA +transfers. Detailed information follows this section. + +- The card raises the Encoder interrupt. +- The driver reads the transfer type, offset and size from Mailbox #10. +- The driver constructs the scatter-gather array from enough free dma buffers + to cover the size. +- The driver schedules the DMA transfer via the ScheduleDMAtoHost API call. +- The card raises the DMA Complete interrupt. +- The driver checks the DMA status register for any errors. +- The driver post-processes the newly transferred buffers. + +NOTE! It is possible that the Encoder and DMA Complete interrupts get raised +simultaneously. (End of the last, start of the next, etc.) + +Mailbox #10 +~~~~~~~~~~~ + +The Flags, Command, Return Value and Timeout fields are ignored. + +- Name: Mailbox #10 +- Results[0]: Type: 0: MPEG. +- Results[1]: Offset: The position relative to the card's memory space. +- Results[2]: Size: The exact number of bytes to transfer. + +My speculation is that since the StartCapture API has a capture type of "RAW" +available, that the type field will have other values that correspond to YUV +and PCM data. + +Scatter-Gather Array +~~~~~~~~~~~~~~~~~~~~ + +The scatter-gather array is a contiguously allocated block of memory that +tells the card the source and destination of each data-block to transfer. +Card "addresses" are derived from the offset supplied by Mailbox #10. Host +addresses are the physical memory location of the target DMA buffer. + +Each S-G array element is a struct of three 32-bit words. The first word is +the source address, the second is the destination address. Both take up the +entire 32 bits. The lowest 18 bits of the third word is the transfer byte +count. The high-bit of the third word is the "last" flag. The last-flag tells +the card to raise the DMA_DONE interrupt. From hard personal experience, if +you forget to set this bit, the card will still "work" but the stream will +most likely get corrupted. + +The transfer count must be a multiple of 256. Therefore, the driver will need +to track how much data in the target buffer is valid and deal with it +accordingly. + +Array Element: + +- 32-bit Source Address +- 32-bit Destination Address +- 14-bit reserved (high bit is the last flag) +- 18-bit byte count + +DMA Transfer Status +~~~~~~~~~~~~~~~~~~~ + +Register 0x0004 holds the DMA Transfer Status: + +- bit 0: read completed +- bit 1: write completed +- bit 2: DMA read error +- bit 3: DMA write error +- bit 4: Scatter-Gather array error diff --git a/Documentation/driver-api/media/drivers/cx88-devel.rst b/Documentation/driver-api/media/drivers/cx88-devel.rst new file mode 100644 index 000000000000..cfe7c03f4930 --- /dev/null +++ b/Documentation/driver-api/media/drivers/cx88-devel.rst @@ -0,0 +1,113 @@ +.. SPDX-License-Identifier: GPL-2.0 + +The cx88 driver +=============== + +Author: Gerd Hoffmann + +Documentation missing at the cx88 datasheet +------------------------------------------- + +MO_OUTPUT_FORMAT (0x310164) + +.. code-block:: none + + Previous default from DScaler: 0x1c1f0008 + Digit 8: 31-28 + 28: PREVREMOD = 1 + + Digit 7: 27-24 (0xc = 12 = b1100 ) + 27: COMBALT = 1 + 26: PAL_INV_PHASE + (DScaler apparently set this to 1, resulted in sucky picture) + + Digits 6,5: 23-16 + 25-16: COMB_RANGE = 0x1f [default] (9 bits -> max 512) + + Digit 4: 15-12 + 15: DISIFX = 0 + 14: INVCBF = 0 + 13: DISADAPT = 0 + 12: NARROWADAPT = 0 + + Digit 3: 11-8 + 11: FORCE2H + 10: FORCEREMD + 9: NCHROMAEN + 8: NREMODEN + + Digit 2: 7-4 + 7-6: YCORE + 5-4: CCORE + + Digit 1: 3-0 + 3: RANGE = 1 + 2: HACTEXT + 1: HSFMT + +0x47 is the sync byte for MPEG-2 transport stream packets. +Datasheet incorrectly states to use 47 decimal. 188 is the length. +All DVB compliant frontends output packets with this start code. + +Hauppauge WinTV cx88 IR information +----------------------------------- + +The controls for the mux are GPIO [0,1] for source, and GPIO 2 for muting. + +====== ======== ================================================= +GPIO0 GPIO1 +====== ======== ================================================= + 0 0 TV Audio + 1 0 FM radio + 0 1 Line-In + 1 1 Mono tuner bypass or CD passthru (tuner specific) +====== ======== ================================================= + +GPIO 16(I believe) is tied to the IR port (if present). + + +From the data sheet: + +- Register 24'h20004 PCI Interrupt Status + + - bit [18] IR_SMP_INT Set when 32 input samples have been collected over + - gpio[16] pin into GP_SAMPLE register. + +What's missing from the data sheet: + +- Setup 4KHz sampling rate (roughly 2x oversampled; good enough for our RC5 + compat remote) +- set register 0x35C050 to 0xa80a80 +- enable sampling +- set register 0x35C054 to 0x5 +- enable the IRQ bit 18 in the interrupt mask register (and + provide for a handler) + +GP_SAMPLE register is at 0x35C058 + +Bits are then right shifted into the GP_SAMPLE register at the specified +rate; you get an interrupt when a full DWORD is received. +You need to recover the actual RC5 bits out of the (oversampled) IR sensor +bits. (Hint: look for the 0/1and 1/0 crossings of the RC5 bi-phase data) An +actual raw RC5 code will span 2-3 DWORDS, depending on the actual alignment. + +I'm pretty sure when no IR signal is present the receiver is always in a +marking state(1); but stray light, etc can cause intermittent noise values +as well. Remember, this is a free running sample of the IR receiver state +over time, so don't assume any sample starts at any particular place. + +Additional info +~~~~~~~~~~~~~~~ + +This data sheet (google search) seems to have a lovely description of the +RC5 basics: +http://www.atmel.com/dyn/resources/prod_documents/doc2817.pdf + +This document has more data: +http://www.nenya.be/beor/electronics/rc5.htm + +This document has a how to decode a bi-phase data stream: +http://www.ee.washington.edu/circuit_archive/text/ir_decode.txt + +This document has still more info: +http://www.xs4all.nl/~sbp/knowledge/ir/rc5.htm diff --git a/Documentation/driver-api/media/drivers/davinci-vpbe-devel.rst b/Documentation/driver-api/media/drivers/davinci-vpbe-devel.rst new file mode 100644 index 000000000000..f0961672e6a3 --- /dev/null +++ b/Documentation/driver-api/media/drivers/davinci-vpbe-devel.rst @@ -0,0 +1,39 @@ +.. SPDX-License-Identifier: GPL-2.0 + +The VPBE V4L2 driver design +=========================== + +File partitioning +----------------- + + V4L2 display device driver + drivers/media/platform/davinci/vpbe_display.c + drivers/media/platform/davinci/vpbe_display.h + + VPBE display controller + drivers/media/platform/davinci/vpbe.c + drivers/media/platform/davinci/vpbe.h + + VPBE venc sub device driver + drivers/media/platform/davinci/vpbe_venc.c + drivers/media/platform/davinci/vpbe_venc.h + drivers/media/platform/davinci/vpbe_venc_regs.h + + VPBE osd driver + drivers/media/platform/davinci/vpbe_osd.c + drivers/media/platform/davinci/vpbe_osd.h + drivers/media/platform/davinci/vpbe_osd_regs.h + +To be done +---------- + +vpbe display controller + - Add support for external encoders. + - add support for selecting external encoder as default at probe time. + +vpbe venc sub device + - add timings for supporting ths8200 + - add support for LogicPD LCD. + +FB drivers + - Add support for fbdev drivers.- Ready and part of subsequent patches. diff --git a/Documentation/driver-api/media/drivers/dvb-usb.rst b/Documentation/driver-api/media/drivers/dvb-usb.rst new file mode 100644 index 000000000000..b2d5d9e62b30 --- /dev/null +++ b/Documentation/driver-api/media/drivers/dvb-usb.rst @@ -0,0 +1,357 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Idea behind the dvb-usb-framework +================================= + +.. note:: + + #) This documentation is outdated. Please check at the DVB wiki + at https://linuxtv.org/wiki for more updated info. + + #) **deprecated:** Newer DVB USB drivers should use the dvb-usb-v2 framework. + +In March 2005 I got the new Twinhan USB2.0 DVB-T device. They provided specs +and a firmware. + +Quite keen I wanted to put the driver (with some quirks of course) into dibusb. +After reading some specs and doing some USB snooping, it realized, that the +dibusb-driver would be a complete mess afterwards. So I decided to do it in a +different way: With the help of a dvb-usb-framework. + +The framework provides generic functions (mostly kernel API calls), such as: + +- Transport Stream URB handling in conjunction with dvb-demux-feed-control + (bulk and isoc are supported) +- registering the device for the DVB-API +- registering an I2C-adapter if applicable +- remote-control/input-device handling +- firmware requesting and loading (currently just for the Cypress USB + controllers) +- other functions/methods which can be shared by several drivers (such as + functions for bulk-control-commands) +- TODO: a I2C-chunker. It creates device-specific chunks of register-accesses + depending on length of a register and the number of values that can be + multi-written and multi-read. + +The source code of the particular DVB USB devices does just the communication +with the device via the bus. The connection between the DVB-API-functionality +is done via callbacks, assigned in a static device-description (struct +dvb_usb_device) each device-driver has to have. + +For an example have a look in drivers/media/usb/dvb-usb/vp7045*. + +Objective is to migrate all the usb-devices (dibusb, cinergyT2, maybe the +ttusb; flexcop-usb already benefits from the generic flexcop-device) to use +the dvb-usb-lib. + +TODO: dynamic enabling and disabling of the pid-filter in regard to number of +feeds requested. + +Supported devices +----------------- + +See the LinuxTV DVB Wiki at https://linuxtv.org for a complete list of +cards/drivers/firmwares: +https://linuxtv.org/wiki/index.php/DVB_USB + +0. History & News: + + 2005-06-30 + + - added support for WideView WT-220U (Thanks to Steve Chang) + + 2005-05-30 + + - added basic isochronous support to the dvb-usb-framework + - added support for Conexant Hybrid reference design and Nebula + DigiTV USB + + 2005-04-17 + + - all dibusb devices ported to make use of the dvb-usb-framework + + 2005-04-02 + + - re-enabled and improved remote control code. + + 2005-03-31 + + - ported the Yakumo/Hama/Typhoon DVB-T USB2.0 device to dvb-usb. + + 2005-03-30 + + - first commit of the dvb-usb-module based on the dibusb-source. + First device is a new driver for the + TwinhanDTV Alpha / MagicBox II USB2.0-only DVB-T device. + - (change from dvb-dibusb to dvb-usb) + + 2005-03-28 + + - added support for the AVerMedia AverTV DVB-T USB2.0 device + (Thanks to Glen Harris and Jiun-Kuei Jung, AVerMedia) + + 2005-03-14 + + - added support for the Typhoon/Yakumo/HAMA DVB-T mobile USB2.0 + + 2005-02-11 + + - added support for the KWorld/ADSTech Instant DVB-T USB2.0. + Thanks a lot to Joachim von Caron + + 2005-02-02 + - added support for the Hauppauge Win-TV Nova-T USB2 + + 2005-01-31 + - distorted streaming is gone for USB1.1 devices + + 2005-01-13 + + - moved the mirrored pid_filter_table back to dvb-dibusb + first almost working version for HanfTek UMT-010 + found out, that Yakumo/HAMA/Typhoon are predecessors of the HanfTek UMT-010 + + 2005-01-10 + + - refactoring completed, now everything is very delightful + + - tuner quirks for some weird devices (Artec T1 AN2235 device has sometimes a + Panasonic Tuner assembled). Tunerprobing implemented. + Thanks a lot to Gunnar Wittich. + + 2004-12-29 + + - after several days of struggling around bug of no returning URBs fixed. + + 2004-12-26 + + - refactored the dibusb-driver, split into separate files + - i2c-probing enabled + + 2004-12-06 + + - possibility for demod i2c-address probing + - new usb IDs (Compro, Artec) + + 2004-11-23 + + - merged changes from DiB3000MC_ver2.1 + - revised the debugging + - possibility to deliver the complete TS for USB2.0 + + 2004-11-21 + + - first working version of the dib3000mc/p frontend driver. + + 2004-11-12 + + - added additional remote control keys. Thanks to Uwe Hanke. + + 2004-11-07 + + - added remote control support. Thanks to David Matthews. + + 2004-11-05 + + - added support for a new devices (Grandtec/Avermedia/Artec) + - merged my changes (for dib3000mb/dibusb) to the FE_REFACTORING, because it became HEAD + - moved transfer control (pid filter, fifo control) from usb driver to frontend, it seems + better settled there (added xfer_ops-struct) + - created a common files for frontends (mc/p/mb) + + 2004-09-28 + + - added support for a new device (Unknown, vendor ID is Hyper-Paltek) + + 2004-09-20 + + - added support for a new device (Compro DVB-U2000), thanks + to Amaury Demol for reporting + - changed usb TS transfer method (several urbs, stopping transfer + before setting a new pid) + + 2004-09-13 + + - added support for a new device (Artec T1 USB TVBOX), thanks + to Christian Motschke for reporting + + 2004-09-05 + + - released the dibusb device and dib3000mb-frontend driver + (old news for vp7041.c) + + 2004-07-15 + + - found out, by accident, that the device has a TUA6010XS for PLL + + 2004-07-12 + + - figured out, that the driver should also work with the + CTS Portable (Chinese Television System) + + 2004-07-08 + + - firmware-extraction-2.422-problem solved, driver is now working + properly with firmware extracted from 2.422 + - #if for 2.6.4 (dvb), compile issue + - changed firmware handling, see vp7041.txt sec 1.1 + + 2004-07-02 + + - some tuner modifications, v0.1, cleanups, first public + + 2004-06-28 + + - now using the dvb_dmx_swfilter_packets, everything runs fine now + + 2004-06-27 + + - able to watch and switching channels (pre-alpha) + - no section filtering yet + + 2004-06-06 + + - first TS received, but kernel oops :/ + + 2004-05-14 + + - firmware loader is working + + 2004-05-11 + + - start writing the driver + +How to use? +----------- + +Firmware +~~~~~~~~ + +Most of the USB drivers need to download a firmware to the device before start +working. + +Have a look at the Wikipage for the DVB-USB-drivers to find out, which firmware +you need for your device: + +https://linuxtv.org/wiki/index.php/DVB_USB + +Compiling +~~~~~~~~~ + +Since the driver is in the linux kernel, activating the driver in +your favorite config-environment should sufficient. I recommend +to compile the driver as module. Hotplug does the rest. + +If you use dvb-kernel enter the build-2.6 directory run 'make' and 'insmod.sh +load' afterwards. + +Loading the drivers +~~~~~~~~~~~~~~~~~~~ + +Hotplug is able to load the driver, when it is needed (because you plugged +in the device). + +If you want to enable debug output, you have to load the driver manually and +from within the dvb-kernel cvs repository. + +first have a look, which debug level are available: + +.. code-block:: none + + # modinfo dvb-usb + # modinfo dvb-usb-vp7045 + + etc. + +.. code-block:: none + + modprobe dvb-usb debug=<level> + modprobe dvb-usb-vp7045 debug=<level> + etc. + +should do the trick. + +When the driver is loaded successfully, the firmware file was in +the right place and the device is connected, the "Power"-LED should be +turned on. + +At this point you should be able to start a dvb-capable application. I'm use +(t|s)zap, mplayer and dvbscan to test the basics. VDR-xine provides the +long-term test scenario. + +Known problems and bugs +----------------------- + +- Don't remove the USB device while running an DVB application, your system + will go crazy or die most likely. + +Adding support for devices +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +TODO + +USB1.1 Bandwidth limitation +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A lot of the currently supported devices are USB1.1 and thus they have a +maximum bandwidth of about 5-6 MBit/s when connected to a USB2.0 hub. +This is not enough for receiving the complete transport stream of a +DVB-T channel (which is about 16 MBit/s). Normally this is not a +problem, if you only want to watch TV (this does not apply for HDTV), +but watching a channel while recording another channel on the same +frequency simply does not work very well. This applies to all USB1.1 +DVB-T devices, not just the dvb-usb-devices) + +The bug, where the TS is distorted by a heavy usage of the device is gone +definitely. All dvb-usb-devices I was using (Twinhan, Kworld, DiBcom) are +working like charm now with VDR. Sometimes I even was able to record a channel +and watch another one. + +Comments +~~~~~~~~ + +Patches, comments and suggestions are very very welcome. + +3. Acknowledgements +------------------- + + Amaury Demol (Amaury.Demol@parrot.com) and Francois Kanounnikoff from DiBcom for + providing specs, code and help, on which the dvb-dibusb, dib3000mb and + dib3000mc are based. + + David Matthews for identifying a new device type (Artec T1 with AN2235) + and for extending dibusb with remote control event handling. Thank you. + + Alex Woods for frequently answering question about usb and dvb + stuff, a big thank you. + + Bernd Wagner for helping with huge bug reports and discussions. + + Gunnar Wittich and Joachim von Caron for their trust for providing + root-shells on their machines to implement support for new devices. + + Allan Third and Michael Hutchinson for their help to write the Nebula + digitv-driver. + + Glen Harris for bringing up, that there is a new dibusb-device and Jiun-Kuei + Jung from AVerMedia who kindly provided a special firmware to get the device + up and running in Linux. + + Jennifer Chen, Jeff and Jack from Twinhan for kindly supporting by + writing the vp7045-driver. + + Steve Chang from WideView for providing information for new devices and + firmware files. + + Michael Paxton for submitting remote control keymaps. + + Some guys on the linux-dvb mailing list for encouraging me. + + Peter Schildmann >peter.schildmann-nospam-at-web.de< for his + user-level firmware loader, which saves a lot of time + (when writing the vp7041 driver) + + Ulf Hermenau for helping me out with traditional chinese. + + André Smoktun and Christian Frömmel for supporting me with + hardware and listening to my problems very patiently. diff --git a/Documentation/driver-api/media/drivers/fimc-devel.rst b/Documentation/driver-api/media/drivers/fimc-devel.rst new file mode 100644 index 000000000000..956e3a9901f8 --- /dev/null +++ b/Documentation/driver-api/media/drivers/fimc-devel.rst @@ -0,0 +1,33 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: <isonum.txt> + +The Samsung S5P/EXYNOS4 FIMC driver +=================================== + +Copyright |copy| 2012 - 2013 Samsung Electronics Co., Ltd. + +Files partitioning +------------------ + +- media device driver + + drivers/media/platform/exynos4-is/media-dev.[ch] + +- camera capture video device driver + + drivers/media/platform/exynos4-is/fimc-capture.c + +- MIPI-CSI2 receiver subdev + + drivers/media/platform/exynos4-is/mipi-csis.[ch] + +- video post-processor (mem-to-mem) + + drivers/media/platform/exynos4-is/fimc-core.c + +- common files + + drivers/media/platform/exynos4-is/fimc-core.h + drivers/media/platform/exynos4-is/fimc-reg.h + drivers/media/platform/exynos4-is/regs-fimc.h diff --git a/Documentation/driver-api/media/drivers/frontends.rst b/Documentation/driver-api/media/drivers/frontends.rst new file mode 100644 index 000000000000..7b8336ece681 --- /dev/null +++ b/Documentation/driver-api/media/drivers/frontends.rst @@ -0,0 +1,32 @@ +.. SPDX-License-Identifier: GPL-2.0 + +**************** +Frontend drivers +**************** + +Frontend attach headers +*********************** + +.. Keep it on alphabetic order + +.. kernel-doc:: drivers/media/dvb-frontends/a8293.h +.. kernel-doc:: drivers/media/dvb-frontends/af9013.h +.. kernel-doc:: drivers/media/dvb-frontends/ascot2e.h +.. kernel-doc:: drivers/media/dvb-frontends/cxd2820r.h +.. kernel-doc:: drivers/media/dvb-frontends/drxk.h +.. kernel-doc:: drivers/media/dvb-frontends/dvb-pll.h +.. kernel-doc:: drivers/media/dvb-frontends/helene.h +.. kernel-doc:: drivers/media/dvb-frontends/horus3a.h +.. kernel-doc:: drivers/media/dvb-frontends/ix2505v.h +.. kernel-doc:: drivers/media/dvb-frontends/m88ds3103.h +.. kernel-doc:: drivers/media/dvb-frontends/mb86a20s.h +.. kernel-doc:: drivers/media/dvb-frontends/mn88472.h +.. kernel-doc:: drivers/media/dvb-frontends/rtl2830.h +.. kernel-doc:: drivers/media/dvb-frontends/rtl2832.h +.. kernel-doc:: drivers/media/dvb-frontends/rtl2832_sdr.h +.. kernel-doc:: drivers/media/dvb-frontends/stb6000.h +.. kernel-doc:: drivers/media/dvb-frontends/tda10071.h +.. kernel-doc:: drivers/media/dvb-frontends/tda826x.h +.. kernel-doc:: drivers/media/dvb-frontends/zd1301_demod.h +.. kernel-doc:: drivers/media/dvb-frontends/zl10036.h + diff --git a/Documentation/driver-api/media/drivers/index.rst b/Documentation/driver-api/media/drivers/index.rst new file mode 100644 index 000000000000..0df85fc96605 --- /dev/null +++ b/Documentation/driver-api/media/drivers/index.rst @@ -0,0 +1,38 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: <isonum.txt> + +=================================== +Media driver-specific documentation +=================================== + +Video4Linux (V4L) drivers +========================= + +.. toctree:: + :maxdepth: 5 + + bttv-devel + cpia2_devel + cx2341x-devel + cx88-devel + davinci-vpbe-devel + fimc-devel + pvrusb2 + pxa_camera + radiotrack + saa7134-devel + sh_mobile_ceu_camera + tuners + vimc-devel + + +Digital TV drivers +================== + +.. toctree:: + :maxdepth: 5 + + dvb-usb + frontends + contributors diff --git a/Documentation/driver-api/media/drivers/pvrusb2.rst b/Documentation/driver-api/media/drivers/pvrusb2.rst new file mode 100644 index 000000000000..83bfaa531ea8 --- /dev/null +++ b/Documentation/driver-api/media/drivers/pvrusb2.rst @@ -0,0 +1,202 @@ +.. SPDX-License-Identifier: GPL-2.0 + +The pvrusb2 driver +================== + +Author: Mike Isely <isely@pobox.com> + +Background +---------- + +This driver is intended for the "Hauppauge WinTV PVR USB 2.0", which +is a USB 2.0 hosted TV Tuner. This driver is a work in progress. +Its history started with the reverse-engineering effort by Björn +Danielsson <pvrusb2@dax.nu> whose web page can be found here: +http://pvrusb2.dax.nu/ + +From there Aurelien Alleaume <slts@free.fr> began an effort to +create a video4linux compatible driver. I began with Aurelien's +last known snapshot and evolved the driver to the state it is in +here. + +More information on this driver can be found at: +http://www.isely.net/pvrusb2.html + + +This driver has a strong separation of layers. They are very +roughly: + +1. Low level wire-protocol implementation with the device. + +2. I2C adaptor implementation and corresponding I2C client drivers + implemented elsewhere in V4L. + +3. High level hardware driver implementation which coordinates all + activities that ensure correct operation of the device. + +4. A "context" layer which manages instancing of driver, setup, + tear-down, arbitration, and interaction with high level + interfaces appropriately as devices are hotplugged in the + system. + +5. High level interfaces which glue the driver to various published + Linux APIs (V4L, sysfs, maybe DVB in the future). + +The most important shearing layer is between the top 2 layers. A +lot of work went into the driver to ensure that any kind of +conceivable API can be laid on top of the core driver. (Yes, the +driver internally leverages V4L to do its work but that really has +nothing to do with the API published by the driver to the outside +world.) The architecture allows for different APIs to +simultaneously access the driver. I have a strong sense of fairness +about APIs and also feel that it is a good design principle to keep +implementation and interface isolated from each other. Thus while +right now the V4L high level interface is the most complete, the +sysfs high level interface will work equally well for similar +functions, and there's no reason I see right now why it shouldn't be +possible to produce a DVB high level interface that can sit right +alongside V4L. + +Building +-------- + +To build these modules essentially amounts to just running "Make", +but you need the kernel source tree nearby and you will likely also +want to set a few controlling environment variables first in order +to link things up with that source tree. Please see the Makefile +here for comments that explain how to do that. + +Source file list / functional overview +-------------------------------------- + +(Note: The term "module" used below generally refers to loosely +defined functional units within the pvrusb2 driver and bears no +relation to the Linux kernel's concept of a loadable module.) + +pvrusb2-audio.[ch] - This is glue logic that resides between this + driver and the msp3400.ko I2C client driver (which is found + elsewhere in V4L). + +pvrusb2-context.[ch] - This module implements the context for an + instance of the driver. Everything else eventually ties back to + or is otherwise instanced within the data structures implemented + here. Hotplugging is ultimately coordinated here. All high level + interfaces tie into the driver through this module. This module + helps arbitrate each interface's access to the actual driver core, + and is designed to allow concurrent access through multiple + instances of multiple interfaces (thus you can for example change + the tuner's frequency through sysfs while simultaneously streaming + video through V4L out to an instance of mplayer). + +pvrusb2-debug.h - This header defines a printk() wrapper and a mask + of debugging bit definitions for the various kinds of debug + messages that can be enabled within the driver. + +pvrusb2-debugifc.[ch] - This module implements a crude command line + oriented debug interface into the driver. Aside from being part + of the process for implementing manual firmware extraction (see + the pvrusb2 web site mentioned earlier), probably I'm the only one + who has ever used this. It is mainly a debugging aid. + +pvrusb2-eeprom.[ch] - This is glue logic that resides between this + driver the tveeprom.ko module, which is itself implemented + elsewhere in V4L. + +pvrusb2-encoder.[ch] - This module implements all protocol needed to + interact with the Conexant mpeg2 encoder chip within the pvrusb2 + device. It is a crude echo of corresponding logic in ivtv, + however the design goals (strict isolation) and physical layer + (proxy through USB instead of PCI) are enough different that this + implementation had to be completely different. + +pvrusb2-hdw-internal.h - This header defines the core data structure + in the driver used to track ALL internal state related to control + of the hardware. Nobody outside of the core hardware-handling + modules should have any business using this header. All external + access to the driver should be through one of the high level + interfaces (e.g. V4L, sysfs, etc), and in fact even those high + level interfaces are restricted to the API defined in + pvrusb2-hdw.h and NOT this header. + +pvrusb2-hdw.h - This header defines the full internal API for + controlling the hardware. High level interfaces (e.g. V4L, sysfs) + will work through here. + +pvrusb2-hdw.c - This module implements all the various bits of logic + that handle overall control of a specific pvrusb2 device. + (Policy, instantiation, and arbitration of pvrusb2 devices fall + within the jurisdiction of pvrusb-context not here). + +pvrusb2-i2c-chips-\*.c - These modules implement the glue logic to + tie together and configure various I2C modules as they attach to + the I2C bus. There are two versions of this file. The "v4l2" + version is intended to be used in-tree alongside V4L, where we + implement just the logic that makes sense for a pure V4L + environment. The "all" version is intended for use outside of + V4L, where we might encounter other possibly "challenging" modules + from ivtv or older kernel snapshots (or even the support modules + in the standalone snapshot). + +pvrusb2-i2c-cmd-v4l1.[ch] - This module implements generic V4L1 + compatible commands to the I2C modules. It is here where state + changes inside the pvrusb2 driver are translated into V4L1 + commands that are in turn send to the various I2C modules. + +pvrusb2-i2c-cmd-v4l2.[ch] - This module implements generic V4L2 + compatible commands to the I2C modules. It is here where state + changes inside the pvrusb2 driver are translated into V4L2 + commands that are in turn send to the various I2C modules. + +pvrusb2-i2c-core.[ch] - This module provides an implementation of a + kernel-friendly I2C adaptor driver, through which other external + I2C client drivers (e.g. msp3400, tuner, lirc) may connect and + operate corresponding chips within the pvrusb2 device. It is + through here that other V4L modules can reach into this driver to + operate specific pieces (and those modules are in turn driven by + glue logic which is coordinated by pvrusb2-hdw, doled out by + pvrusb2-context, and then ultimately made available to users + through one of the high level interfaces). + +pvrusb2-io.[ch] - This module implements a very low level ring of + transfer buffers, required in order to stream data from the + device. This module is *very* low level. It only operates the + buffers and makes no attempt to define any policy or mechanism for + how such buffers might be used. + +pvrusb2-ioread.[ch] - This module layers on top of pvrusb2-io.[ch] + to provide a streaming API usable by a read() system call style of + I/O. Right now this is the only layer on top of pvrusb2-io.[ch], + however the underlying architecture here was intended to allow for + other styles of I/O to be implemented with additional modules, like + mmap()'ed buffers or something even more exotic. + +pvrusb2-main.c - This is the top level of the driver. Module level + and USB core entry points are here. This is our "main". + +pvrusb2-sysfs.[ch] - This is the high level interface which ties the + pvrusb2 driver into sysfs. Through this interface you can do + everything with the driver except actually stream data. + +pvrusb2-tuner.[ch] - This is glue logic that resides between this + driver and the tuner.ko I2C client driver (which is found + elsewhere in V4L). + +pvrusb2-util.h - This header defines some common macros used + throughout the driver. These macros are not really specific to + the driver, but they had to go somewhere. + +pvrusb2-v4l2.[ch] - This is the high level interface which ties the + pvrusb2 driver into video4linux. It is through here that V4L + applications can open and operate the driver in the usual V4L + ways. Note that **ALL** V4L functionality is published only + through here and nowhere else. + +pvrusb2-video-\*.[ch] - This is glue logic that resides between this + driver and the saa711x.ko I2C client driver (which is found + elsewhere in V4L). Note that saa711x.ko used to be known as + saa7115.ko in ivtv. There are two versions of this; one is + selected depending on the particular saa711[5x].ko that is found. + +pvrusb2.h - This header contains compile time tunable parameters + (and at the moment the driver has very little that needs to be + tuned). diff --git a/Documentation/driver-api/media/drivers/pxa_camera.rst b/Documentation/driver-api/media/drivers/pxa_camera.rst new file mode 100644 index 000000000000..ee1bd96b66dd --- /dev/null +++ b/Documentation/driver-api/media/drivers/pxa_camera.rst @@ -0,0 +1,194 @@ +.. SPDX-License-Identifier: GPL-2.0 + +PXA-Camera Host Driver +====================== + +Author: Robert Jarzmik <robert.jarzmik@free.fr> + +Constraints +----------- + +a) Image size for YUV422P format + All YUV422P images are enforced to have width x height % 16 = 0. + This is due to DMA constraints, which transfers only planes of 8 byte + multiples. + + +Global video workflow +--------------------- + +a) QCI stopped + Initially, the QCI interface is stopped. + When a buffer is queued (pxa_videobuf_ops->buf_queue), the QCI starts. + +b) QCI started + More buffers can be queued while the QCI is started without halting the + capture. The new buffers are "appended" at the tail of the DMA chain, and + smoothly captured one frame after the other. + + Once a buffer is filled in the QCI interface, it is marked as "DONE" and + removed from the active buffers list. It can be then requeud or dequeued by + userland application. + + Once the last buffer is filled in, the QCI interface stops. + +c) Capture global finite state machine schema + +.. code-block:: none + + +----+ +---+ +----+ + | DQ | | Q | | DQ | + | v | v | v + +-----------+ +------------------------+ + | STOP | | Wait for capture start | + +-----------+ Q +------------------------+ + +-> | QCI: stop | ------------------> | QCI: run | <------------+ + | | DMA: stop | | DMA: stop | | + | +-----------+ +-----> +------------------------+ | + | / | | + | / +---+ +----+ | | + |capture list empty / | Q | | DQ | | QCI Irq EOF | + | / | v | v v | + | +--------------------+ +----------------------+ | + | | DMA hotlink missed | | Capture running | | + | +--------------------+ +----------------------+ | + | | QCI: run | +-----> | QCI: run | <-+ | + | | DMA: stop | / | DMA: run | | | + | +--------------------+ / +----------------------+ | Other | + | ^ /DMA still | | channels | + | | capture list / running | DMA Irq End | not | + | | not empty / | | finished | + | | / v | yet | + | +----------------------+ +----------------------+ | | + | | Videobuf released | | Channel completed | | | + | +----------------------+ +----------------------+ | | + +-- | QCI: run | | QCI: run | --+ | + | DMA: run | | DMA: run | | + +----------------------+ +----------------------+ | + ^ / | | + | no overrun / | overrun | + | / v | + +--------------------+ / +----------------------+ | + | Frame completed | / | Frame overran | | + +--------------------+ <-----+ +----------------------+ restart frame | + | QCI: run | | QCI: stop | --------------+ + | DMA: run | | DMA: stop | + +--------------------+ +----------------------+ + + Legend: - each box is a FSM state + - each arrow is the condition to transition to another state + - an arrow with a comment is a mandatory transition (no condition) + - arrow "Q" means : a buffer was enqueued + - arrow "DQ" means : a buffer was dequeued + - "QCI: stop" means the QCI interface is not enabled + - "DMA: stop" means all 3 DMA channels are stopped + - "DMA: run" means at least 1 DMA channel is still running + +DMA usage +--------- + +a) DMA flow + - first buffer queued for capture + Once a first buffer is queued for capture, the QCI is started, but data + transfer is not started. On "End Of Frame" interrupt, the irq handler + starts the DMA chain. + - capture of one videobuffer + The DMA chain starts transferring data into videobuffer RAM pages. + When all pages are transferred, the DMA irq is raised on "ENDINTR" status + - finishing one videobuffer + The DMA irq handler marks the videobuffer as "done", and removes it from + the active running queue + Meanwhile, the next videobuffer (if there is one), is transferred by DMA + - finishing the last videobuffer + On the DMA irq of the last videobuffer, the QCI is stopped. + +b) DMA prepared buffer will have this structure + +.. code-block:: none + + +------------+-----+---------------+-----------------+ + | desc-sg[0] | ... | desc-sg[last] | finisher/linker | + +------------+-----+---------------+-----------------+ + +This structure is pointed by dma->sg_cpu. +The descriptors are used as follows: + +- desc-sg[i]: i-th descriptor, transferring the i-th sg + element to the video buffer scatter gather +- finisher: has ddadr=DADDR_STOP, dcmd=ENDIRQEN +- linker: has ddadr= desc-sg[0] of next video buffer, dcmd=0 + +For the next schema, let's assume d0=desc-sg[0] .. dN=desc-sg[N], +"f" stands for finisher and "l" for linker. +A typical running chain is : + +.. code-block:: none + + Videobuffer 1 Videobuffer 2 + +---------+----+---+ +----+----+----+---+ + | d0 | .. | dN | l | | d0 | .. | dN | f | + +---------+----+-|-+ ^----+----+----+---+ + | | + +----+ + +After the chaining is finished, the chain looks like : + +.. code-block:: none + + Videobuffer 1 Videobuffer 2 Videobuffer 3 + +---------+----+---+ +----+----+----+---+ +----+----+----+---+ + | d0 | .. | dN | l | | d0 | .. | dN | l | | d0 | .. | dN | f | + +---------+----+-|-+ ^----+----+----+-|-+ ^----+----+----+---+ + | | | | + +----+ +----+ + new_link + +c) DMA hot chaining timeslice issue + +As DMA chaining is done while DMA _is_ running, the linking may be done +while the DMA jumps from one Videobuffer to another. On the schema, that +would be a problem if the following sequence is encountered : + +- DMA chain is Videobuffer1 + Videobuffer2 +- pxa_videobuf_queue() is called to queue Videobuffer3 +- DMA controller finishes Videobuffer2, and DMA stops + +.. code-block:: none + + => + Videobuffer 1 Videobuffer 2 + +---------+----+---+ +----+----+----+---+ + | d0 | .. | dN | l | | d0 | .. | dN | f | + +---------+----+-|-+ ^----+----+----+-^-+ + | | | + +----+ +-- DMA DDADR loads DDADR_STOP + +- pxa_dma_add_tail_buf() is called, the Videobuffer2 "finisher" is + replaced by a "linker" to Videobuffer3 (creation of new_link) +- pxa_videobuf_queue() finishes +- the DMA irq handler is called, which terminates Videobuffer2 +- Videobuffer3 capture is not scheduled on DMA chain (as it stopped !!!) + +.. code-block:: none + + Videobuffer 1 Videobuffer 2 Videobuffer 3 + +---------+----+---+ +----+----+----+---+ +----+----+----+---+ + | d0 | .. | dN | l | | d0 | .. | dN | l | | d0 | .. | dN | f | + +---------+----+-|-+ ^----+----+----+-|-+ ^----+----+----+---+ + | | | | + +----+ +----+ + new_link + DMA DDADR still is DDADR_STOP + +- pxa_camera_check_link_miss() is called + This checks if the DMA is finished and a buffer is still on the + pcdev->capture list. If that's the case, the capture will be restarted, + and Videobuffer3 is scheduled on DMA chain. +- the DMA irq handler finishes + +.. note:: + + If DMA stops just after pxa_camera_check_link_miss() reads DDADR() + value, we have the guarantee that the DMA irq handler will be called back + when the DMA will finish the buffer, and pxa_camera_check_link_miss() will + be called again, to reschedule Videobuffer3. diff --git a/Documentation/driver-api/media/drivers/radiotrack.rst b/Documentation/driver-api/media/drivers/radiotrack.rst new file mode 100644 index 000000000000..a85cb6205db8 --- /dev/null +++ b/Documentation/driver-api/media/drivers/radiotrack.rst @@ -0,0 +1,168 @@ +.. SPDX-License-Identifier: GPL-2.0 + +The Radiotrack radio driver +=========================== + +Author: Stephen M. Benoit <benoits@servicepro.com> + +Date: Dec 14, 1996 + +ACKNOWLEDGMENTS +---------------- + +This document was made based on 'C' code for Linux from Gideon le Grange +(legrang@active.co.za or legrang@cs.sun.ac.za) in 1994, and elaborations from +Frans Brinkman (brinkman@esd.nl) in 1996. The results reported here are from +experiments that the author performed on his own setup, so your mileage may +vary... I make no guarantees, claims or warranties to the suitability or +validity of this information. No other documentation on the AIMS +Lab (http://www.aimslab.com/) RadioTrack card was made available to the +author. This document is offered in the hopes that it might help users who +want to use the RadioTrack card in an environment other than MS Windows. + +WHY THIS DOCUMENT? +------------------ + +I have a RadioTrack card from back when I ran an MS-Windows platform. After +converting to Linux, I found Gideon le Grange's command-line software for +running the card, and found that it was good! Frans Brinkman made a +comfortable X-windows interface, and added a scanning feature. For hack +value, I wanted to see if the tuner could be tuned beyond the usual FM radio +broadcast band, so I could pick up the audio carriers from North American +broadcast TV channels, situated just below and above the 87.0-109.0 MHz range. +I did not get much success, but I learned about programming ioports under +Linux and gained some insights about the hardware design used for the card. + +So, without further delay, here are the details. + + +PHYSICAL DESCRIPTION +-------------------- + +The RadioTrack card is an ISA 8-bit FM radio card. The radio frequency (RF) +input is simply an antenna lead, and the output is a power audio signal +available through a miniature phone plug. Its RF frequencies of operation are +more or less limited from 87.0 to 109.0 MHz (the commercial FM broadcast +band). Although the registers can be programmed to request frequencies beyond +these limits, experiments did not give promising results. The variable +frequency oscillator (VFO) that demodulates the intermediate frequency (IF) +signal probably has a small range of useful frequencies, and wraps around or +gets clipped beyond the limits mentioned above. + + +CONTROLLING THE CARD WITH IOPORT +-------------------------------- + +The RadioTrack (base) ioport is configurable for 0x30c or 0x20c. Only one +ioport seems to be involved. The ioport decoding circuitry must be pretty +simple, as individual ioport bits are directly matched to specific functions +(or blocks) of the radio card. This way, many functions can be changed in +parallel with one write to the ioport. The only feedback available through +the ioports appears to be the "Stereo Detect" bit. + +The bits of the ioport are arranged as follows: + +.. code-block:: none + + MSb LSb + +------+------+------+--------+--------+-------+---------+--------+ + | VolA | VolB | ???? | Stereo | Radio | TuneA | TuneB | Tune | + | (+) | (-) | | Detect | Audio | (bit) | (latch) | Update | + | | | | Enable | Enable | | | Enable | + +------+------+------+--------+--------+-------+---------+--------+ + + +==== ==== ================================= +VolA VolB Description +==== ==== ================================= +0 0 audio mute +0 1 volume + (some delay required) +1 0 volume - (some delay required) +1 1 stay at present volume +==== ==== ================================= + +==================== =========== +Stereo Detect Enable Description +==================== =========== +0 No Detect +1 Detect +==================== =========== + +Results available by reading ioport >60 msec after last port write. + + 0xff ==> no stereo detected, 0xfd ==> stereo detected. + +============================= ============================= +Radio to Audio (path) Enable Description +============================= ============================= +0 Disable path (silence) +1 Enable path (audio produced) +============================= ============================= + +===== ===== ================== +TuneA TuneB Description +===== ===== ================== +0 0 "zero" bit phase 1 +0 1 "zero" bit phase 2 +1 0 "one" bit phase 1 +1 1 "one" bit phase 2 +===== ===== ================== + + +24-bit code, where bits = (freq*40) + 10486188. +The Most Significant 11 bits must be 1010 xxxx 0x0 to be valid. +The bits are shifted in LSb first. + +================== =========================== +Tune Update Enable Description +================== =========================== +0 Tuner held constant +1 Tuner updating in progress +================== =========================== + + +PROGRAMMING EXAMPLES +-------------------- + +.. code-block:: none + + Default: BASE <-- 0xc8 (current volume, no stereo detect, + radio enable, tuner adjust disable) + + Card Off: BASE <-- 0x00 (audio mute, no stereo detect, + radio disable, tuner adjust disable) + + Card On: BASE <-- 0x00 (see "Card Off", clears any unfinished business) + BASE <-- 0xc8 (see "Default") + + Volume Down: BASE <-- 0x48 (volume down, no stereo detect, + radio enable, tuner adjust disable) + wait 10 msec + BASE <-- 0xc8 (see "Default") + + Volume Up: BASE <-- 0x88 (volume up, no stereo detect, + radio enable, tuner adjust disable) + wait 10 msec + BASE <-- 0xc8 (see "Default") + + Check Stereo: BASE <-- 0xd8 (current volume, stereo detect, + radio enable, tuner adjust disable) + wait 100 msec + x <-- BASE (read ioport) + BASE <-- 0xc8 (see "Default") + + x=0xff ==> "not stereo", x=0xfd ==> "stereo detected" + + Set Frequency: code = (freq*40) + 10486188 + foreach of the 24 bits in code, + (from Least to Most Significant): + to write a "zero" bit, + BASE <-- 0x01 (audio mute, no stereo detect, radio + disable, "zero" bit phase 1, tuner adjust) + BASE <-- 0x03 (audio mute, no stereo detect, radio + disable, "zero" bit phase 2, tuner adjust) + to write a "one" bit, + BASE <-- 0x05 (audio mute, no stereo detect, radio + disable, "one" bit phase 1, tuner adjust) + BASE <-- 0x07 (audio mute, no stereo detect, radio + disable, "one" bit phase 2, tuner adjust) diff --git a/Documentation/driver-api/media/drivers/saa7134-devel.rst b/Documentation/driver-api/media/drivers/saa7134-devel.rst new file mode 100644 index 000000000000..167fd729bc8c --- /dev/null +++ b/Documentation/driver-api/media/drivers/saa7134-devel.rst @@ -0,0 +1,67 @@ +.. SPDX-License-Identifier: GPL-2.0 + +The saa7134 driver +================== + +Author Gerd Hoffmann + + +Card Variations: +---------------- + +Cards can use either of these two crystals (xtal): + +- 32.11 MHz -> .audio_clock=0x187de7 +- 24.576MHz -> .audio_clock=0x200000 (xtal * .audio_clock = 51539600) + +Some details about 30/34/35: + +- saa7130 - low-price chip, doesn't have mute, that is why all those + cards should have .mute field defined in their tuner structure. + +- saa7134 - usual chip + +- saa7133/35 - saa7135 is probably a marketing decision, since all those + chips identifies itself as 33 on pci. + +LifeView GPIOs +-------------- + +This section was authored by: Peter Missel <peter.missel@onlinehome.de> + +- LifeView FlyTV Platinum FM (LR214WF) + + - GP27 MDT2005 PB4 pin 10 + - GP26 MDT2005 PB3 pin 9 + - GP25 MDT2005 PB2 pin 8 + - GP23 MDT2005 PB1 pin 7 + - GP22 MDT2005 PB0 pin 6 + - GP21 MDT2005 PB5 pin 11 + - GP20 MDT2005 PB6 pin 12 + - GP19 MDT2005 PB7 pin 13 + - nc MDT2005 PA3 pin 2 + - Remote MDT2005 PA2 pin 1 + - GP18 MDT2005 PA1 pin 18 + - nc MDT2005 PA0 pin 17 strap low + - GP17 Strap "GP7"=High + - GP16 Strap "GP6"=High + + - 0=Radio 1=TV + - Drives SA630D ENCH1 and HEF4052 A1 pinsto do FM radio through + SIF input + + - GP15 nc + - GP14 nc + - GP13 nc + - GP12 Strap "GP5" = High + - GP11 Strap "GP4" = High + - GP10 Strap "GP3" = High + - GP09 Strap "GP2" = Low + - GP08 Strap "GP1" = Low + - GP07.00 nc + +Credits +------- + +andrew.stevens@philips.com + werner.leeb@philips.com for providing +saa7134 hardware specs and sample board. diff --git a/Documentation/driver-api/media/drivers/sh_mobile_ceu_camera.rst b/Documentation/driver-api/media/drivers/sh_mobile_ceu_camera.rst new file mode 100644 index 000000000000..822fcb8368ae --- /dev/null +++ b/Documentation/driver-api/media/drivers/sh_mobile_ceu_camera.rst @@ -0,0 +1,142 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Cropping and Scaling algorithm, used in the sh_mobile_ceu_camera driver +======================================================================= + +Author: Guennadi Liakhovetski <g.liakhovetski@gmx.de> + +Terminology +----------- + +sensor scales: horizontal and vertical scales, configured by the sensor driver +host scales: -"- host driver +combined scales: sensor_scale * host_scale + + +Generic scaling / cropping scheme +--------------------------------- + +.. code-block:: none + + -1-- + | + -2-- -\ + | --\ + | --\ + +-5-- . -- -3-- -\ + | `... -\ + | `... -4-- . - -7.. + | `. + | `. .6-- + | + | . .6'- + | .´ + | ... -4'- .´ + | ...´ - -7'. + +-5'- .´ -/ + | -- -3'- -/ + | --/ + | --/ + -2'- -/ + | + | + -1'- + +In the above chart minuses and slashes represent "real" data amounts, points and +accents represent "useful" data, basically, CEU scaled and cropped output, +mapped back onto the client's source plane. + +Such a configuration can be produced by user requests: + +S_CROP(left / top = (5) - (1), width / height = (5') - (5)) +S_FMT(width / height = (6') - (6)) + +Here: + +(1) to (1') - whole max width or height +(1) to (2) - sensor cropped left or top +(2) to (2') - sensor cropped width or height +(3) to (3') - sensor scale +(3) to (4) - CEU cropped left or top +(4) to (4') - CEU cropped width or height +(5) to (5') - reverse sensor scale applied to CEU cropped width or height +(2) to (5) - reverse sensor scale applied to CEU cropped left or top +(6) to (6') - CEU scale - user window + + +S_FMT +----- + +Do not touch input rectangle - it is already optimal. + +1. Calculate current sensor scales: + + scale_s = ((2') - (2)) / ((3') - (3)) + +2. Calculate "effective" input crop (sensor subwindow) - CEU crop scaled back at +current sensor scales onto input window - this is user S_CROP: + + width_u = (5') - (5) = ((4') - (4)) * scale_s + +3. Calculate new combined scales from "effective" input window to requested user +window: + + scale_comb = width_u / ((6') - (6)) + +4. Calculate sensor output window by applying combined scales to real input +window: + + width_s_out = ((7') - (7)) = ((2') - (2)) / scale_comb + +5. Apply iterative sensor S_FMT for sensor output window. + + subdev->video_ops->s_fmt(.width = width_s_out) + +6. Retrieve sensor output window (g_fmt) + +7. Calculate new sensor scales: + + scale_s_new = ((3')_new - (3)_new) / ((2') - (2)) + +8. Calculate new CEU crop - apply sensor scales to previously calculated +"effective" crop: + + width_ceu = (4')_new - (4)_new = width_u / scale_s_new + left_ceu = (4)_new - (3)_new = ((5) - (2)) / scale_s_new + +9. Use CEU cropping to crop to the new window: + + ceu_crop(.width = width_ceu, .left = left_ceu) + +10. Use CEU scaling to scale to the requested user window: + + scale_ceu = width_ceu / width + + +S_CROP +------ + +The :ref:`V4L2 crop API <crop-scale>` says: + +"...specification does not define an origin or units. However by convention +drivers should horizontally count unscaled samples relative to 0H." + +We choose to follow the advise and interpret cropping units as client input +pixels. + +Cropping is performed in the following 6 steps: + +1. Request exactly user rectangle from the sensor. + +2. If smaller - iterate until a larger one is obtained. Result: sensor cropped + to 2 : 2', target crop 5 : 5', current output format 6' - 6. + +3. In the previous step the sensor has tried to preserve its output frame as + good as possible, but it could have changed. Retrieve it again. + +4. Sensor scaled to 3 : 3'. Sensor's scale is (2' - 2) / (3' - 3). Calculate + intermediate window: 4' - 4 = (5' - 5) * (3' - 3) / (2' - 2) + +5. Calculate and apply host scale = (6' - 6) / (4' - 4) + +6. Calculate and apply host crop: 6 - 7 = (5 - 2) * (6' - 6) / (5' - 5) diff --git a/Documentation/driver-api/media/drivers/tuners.rst b/Documentation/driver-api/media/drivers/tuners.rst new file mode 100644 index 000000000000..7509be888909 --- /dev/null +++ b/Documentation/driver-api/media/drivers/tuners.rst @@ -0,0 +1,133 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Tuner drivers +============= + +Simple tuner Programming +------------------------ + +There are some flavors of Tuner programming APIs. +These differ mainly by the bandswitch byte. + +- L= LG_API (VHF_LO=0x01, VHF_HI=0x02, UHF=0x08, radio=0x04) +- P= PHILIPS_API (VHF_LO=0xA0, VHF_HI=0x90, UHF=0x30, radio=0x04) +- T= TEMIC_API (VHF_LO=0x02, VHF_HI=0x04, UHF=0x01) +- A= ALPS_API (VHF_LO=0x14, VHF_HI=0x12, UHF=0x11) +- M= PHILIPS_MK3 (VHF_LO=0x01, VHF_HI=0x02, UHF=0x04, radio=0x19) + +Tuner Manufacturers +------------------- + +- SAMSUNG Tuner identification: (e.g. TCPM9091PD27) + +.. code-block:: none + + TCP [ABCJLMNQ] 90[89][125] [DP] [ACD] 27 [ABCD] + [ABCJLMNQ]: + A= BG+DK + B= BG + C= I+DK + J= NTSC-Japan + L= Secam LL + M= BG+I+DK + N= NTSC + Q= BG+I+DK+LL + [89]: ? + [125]: + 2: No FM + 5: With FM + [DP]: + D= NTSC + P= PAL + [ACD]: + A= F-connector + C= Phono connector + D= Din Jack + [ABCD]: + 3-wire/I2C tuning, 2-band/3-band + +These Tuners are PHILIPS_API compatible. + +Philips Tuner identification: (e.g. FM1216MF) + +.. code-block:: none + + F[IRMQ]12[1345]6{MF|ME|MP} + F[IRMQ]: + FI12x6: Tuner Series + FR12x6: Tuner + Radio IF + FM12x6: Tuner + FM + FQ12x6: special + FMR12x6: special + TD15xx: Digital Tuner ATSC + 12[1345]6: + 1216: PAL BG + 1236: NTSC + 1246: PAL I + 1256: Pal DK + {MF|ME|MP} + MF: BG LL w/ Secam (Multi France) + ME: BG DK I LL (Multi Europe) + MP: BG DK I (Multi PAL) + MR: BG DK M (?) + MG: BG DKI M (?) + MK2 series PHILIPS_API, most tuners are compatible to this one ! + MK3 series introduced in 2002 w/ PHILIPS_MK3_API + +Temic Tuner identification: (.e.g 4006FH5) + +.. code-block:: none + + 4[01][0136][269]F[HYNR]5 + 40x2: Tuner (5V/33V), TEMIC_API. + 40x6: Tuner 5V + 41xx: Tuner compact + 40x9: Tuner+FM compact + [0136] + xx0x: PAL BG + xx1x: Pal DK, Secam LL + xx3x: NTSC + xx6x: PAL I + F[HYNR]5 + FH5: Pal BG + FY5: others + FN5: multistandard + FR5: w/ FM radio + 3X xxxx: order number with specific connector + Note: Only 40x2 series has TEMIC_API, all newer tuners have PHILIPS_API. + +LG Innotek Tuner: + +- TPI8NSR11 : NTSC J/M (TPI8NSR01 w/FM) (P,210/497) +- TPI8PSB11 : PAL B/G (TPI8PSB01 w/FM) (P,170/450) +- TAPC-I701 : PAL I (TAPC-I001 w/FM) (P,170/450) +- TPI8PSB12 : PAL D/K+B/G (TPI8PSB02 w/FM) (P,170/450) +- TAPC-H701P: NTSC_JP (TAPC-H001P w/FM) (L,170/450) +- TAPC-G701P: PAL B/G (TAPC-G001P w/FM) (L,170/450) +- TAPC-W701P: PAL I (TAPC-W001P w/FM) (L,170/450) +- TAPC-Q703P: PAL D/K (TAPC-Q001P w/FM) (L,170/450) +- TAPC-Q704P: PAL D/K+I (L,170/450) +- TAPC-G702P: PAL D/K+B/G (L,170/450) + +- TADC-H002F: NTSC (L,175/410?; 2-B, C-W+11, W+12-69) +- TADC-M201D: PAL D/K+B/G+I (L,143/425) (sound control at I2C address 0xc8) +- TADC-T003F: NTSC Taiwan (L,175/410?; 2-B, C-W+11, W+12-69) + +Suffix: + - P= Standard phono female socket + - D= IEC female socket + - F= F-connector + +Other Tuners: + +- TCL2002MB-1 : PAL BG + DK =TUNER_LG_PAL_NEW_TAPC +- TCL2002MB-1F: PAL BG + DK w/FM =PHILIPS_PAL +- TCL2002MI-2 : PAL I = ?? + +ALPS Tuners: + +- Most are LG_API compatible +- TSCH6 has ALPS_API (TSCH5 ?) +- TSBE1 has extra API 05,02,08 Control_byte=0xCB Source:[#f1]_ + +.. [#f1] conexant100029b-PCI-Decoder-ApplicationNote.pdf diff --git a/Documentation/driver-api/media/drivers/vimc-devel.rst b/Documentation/driver-api/media/drivers/vimc-devel.rst new file mode 100644 index 000000000000..9e984f914b13 --- /dev/null +++ b/Documentation/driver-api/media/drivers/vimc-devel.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: GPL-2.0 + +The Virtual Media Controller Driver (vimc) +========================================== + +Source code documentation +------------------------- + +vimc-streamer +~~~~~~~~~~~~~ + +.. kernel-doc:: drivers/media/test-drivers/vimc/vimc-streamer.h + :internal: + +.. kernel-doc:: drivers/media/test-drivers/vimc/vimc-streamer.c diff --git a/Documentation/driver-api/media/dtv-ca.rst b/Documentation/driver-api/media/dtv-ca.rst new file mode 100644 index 000000000000..8a09862b428b --- /dev/null +++ b/Documentation/driver-api/media/dtv-ca.rst @@ -0,0 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Digital TV Conditional Access kABI +---------------------------------- + +.. kernel-doc:: include/media/dvb_ca_en50221.h diff --git a/Documentation/driver-api/media/dtv-common.rst b/Documentation/driver-api/media/dtv-common.rst new file mode 100644 index 000000000000..f8b2c4dc8170 --- /dev/null +++ b/Documentation/driver-api/media/dtv-common.rst @@ -0,0 +1,62 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Digital TV Common functions +--------------------------- + +Math functions +~~~~~~~~~~~~~~ + +Provide some commonly-used math functions, usually required in order to +estimate signal strength and signal to noise measurements in dB. + +.. kernel-doc:: include/media/dvb_math.h + + +DVB devices +~~~~~~~~~~~ + +Those functions are responsible for handling the DVB device nodes. + +.. kernel-doc:: include/media/dvbdev.h + +Digital TV Ring buffer +~~~~~~~~~~~~~~~~~~~~~~ + +Those routines implement ring buffers used to handle digital TV data and +copy it from/to userspace. + +.. note:: + + 1) For performance reasons read and write routines don't check buffer sizes + and/or number of bytes free/available. This has to be done before these + routines are called. For example: + + .. code-block:: c + + /* write @buflen: bytes */ + free = dvb_ringbuffer_free(rbuf); + if (free >= buflen) + count = dvb_ringbuffer_write(rbuf, buffer, buflen); + else + /* do something */ + + /* read min. 1000, max. @bufsize: bytes */ + avail = dvb_ringbuffer_avail(rbuf); + if (avail >= 1000) + count = dvb_ringbuffer_read(rbuf, buffer, min(avail, bufsize)); + else + /* do something */ + + 2) If there is exactly one reader and one writer, there is no need + to lock read or write operations. + Two or more readers must be locked against each other. + Flushing the buffer counts as a read operation. + Resetting the buffer counts as a read and write operation. + Two or more writers must be locked against each other. + +.. kernel-doc:: include/media/dvb_ringbuffer.h + +Digital TV VB2 handler +~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: include/media/dvb_vb2.h diff --git a/Documentation/driver-api/media/dtv-core.rst b/Documentation/driver-api/media/dtv-core.rst new file mode 100644 index 000000000000..82c5b85ed9b1 --- /dev/null +++ b/Documentation/driver-api/media/dtv-core.rst @@ -0,0 +1,39 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Digital TV (DVB) devices +------------------------ + +Digital TV devices are implemented by several different drivers: + +- A bridge driver that is responsible to talk with the bus where the other + devices are connected (PCI, USB, SPI), bind to the other drivers and + implement the digital demux logic (either in software or in hardware); + +- Frontend drivers that are usually implemented as two separate drivers: + + - A tuner driver that implements the logic which commands the part of + the hardware responsible for tuning into a digital TV transponder or + physical channel. The output of a tuner is usually a baseband or + Intermediate Frequency (IF) signal; + + - A demodulator driver (a.k.a "demod") that implements the logic which + commands the digital TV decoding hardware. The output of a demod is + a digital stream, with multiple audio, video and data channels typically + multiplexed using MPEG Transport Stream [#f1]_. + +On most hardware, the frontend drivers talk with the bridge driver using an +I2C bus. + +.. [#f1] Some standards use TCP/IP for multiplexing data, like DVB-H (an + abandoned standard, not used anymore) and ATSC version 3.0 current + proposals. Currently, the DVB subsystem doesn't implement those standards. + + +.. toctree:: + :maxdepth: 1 + + dtv-common + dtv-frontend + dtv-demux + dtv-ca + dtv-net diff --git a/Documentation/driver-api/media/dtv-demux.rst b/Documentation/driver-api/media/dtv-demux.rst new file mode 100644 index 000000000000..c0ae5dec5328 --- /dev/null +++ b/Documentation/driver-api/media/dtv-demux.rst @@ -0,0 +1,84 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Digital TV Demux kABI +--------------------- + +Digital TV Demux +~~~~~~~~~~~~~~~~ + +The Kernel Digital TV Demux kABI defines a driver-internal interface for +registering low-level, hardware specific driver to a hardware independent +demux layer. It is only of interest for Digital TV device driver writers. +The header file for this kABI is named ``demux.h`` and located in +``include/media``. + +The demux kABI should be implemented for each demux in the system. It is +used to select the TS source of a demux and to manage the demux resources. +When the demux client allocates a resource via the demux kABI, it receives +a pointer to the kABI of that resource. + +Each demux receives its TS input from a DVB front-end or from memory, as +set via this demux kABI. In a system with more than one front-end, the kABI +can be used to select one of the DVB front-ends as a TS source for a demux, +unless this is fixed in the HW platform. + +The demux kABI only controls front-ends regarding to their connections with +demuxes; the kABI used to set the other front-end parameters, such as +tuning, are devined via the Digital TV Frontend kABI. + +The functions that implement the abstract interface demux should be defined +static or module private and registered to the Demux core for external +access. It is not necessary to implement every function in the struct +:c:type:`dmx_demux`. For example, a demux interface might support Section filtering, +but not PES filtering. The kABI client is expected to check the value of any +function pointer before calling the function: the value of ``NULL`` means +that the function is not available. + +Whenever the functions of the demux API modify shared data, the +possibilities of lost update and race condition problems should be +addressed, e.g. by protecting parts of code with mutexes. + +Note that functions called from a bottom half context must not sleep. +Even a simple memory allocation without using ``GFP_ATOMIC`` can result in a +kernel thread being put to sleep if swapping is needed. For example, the +Linux Kernel calls the functions of a network device interface from a +bottom half context. Thus, if a demux kABI function is called from network +device code, the function must not sleep. + +Demux Callback API +~~~~~~~~~~~~~~~~~~ + +This kernel-space API comprises the callback functions that deliver filtered +data to the demux client. Unlike the other DVB kABIs, these functions are +provided by the client and called from the demux code. + +The function pointers of this abstract interface are not packed into a +structure as in the other demux APIs, because the callback functions are +registered and used independent of each other. As an example, it is possible +for the API client to provide several callback functions for receiving TS +packets and no callbacks for PES packets or sections. + +The functions that implement the callback API need not be re-entrant: when +a demux driver calls one of these functions, the driver is not allowed to +call the function again before the original call returns. If a callback is +triggered by a hardware interrupt, it is recommended to use the Linux +bottom half mechanism or start a tasklet instead of making the callback +function call directly from a hardware interrupt. + +This mechanism is implemented by :c:func:`dmx_ts_cb()` and :c:func:`dmx_section_cb()` +callbacks. + +Digital TV Demux device registration functions and data structures +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: include/media/dmxdev.h + +High-level Digital TV demux interface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: include/media/dvb_demux.h + +Driver-internal low-level hardware specific driver demux interface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: include/media/demux.h diff --git a/Documentation/driver-api/media/dtv-frontend.rst b/Documentation/driver-api/media/dtv-frontend.rst new file mode 100644 index 000000000000..b362109bb131 --- /dev/null +++ b/Documentation/driver-api/media/dtv-frontend.rst @@ -0,0 +1,445 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Digital TV Frontend kABI +------------------------ + +Digital TV Frontend +~~~~~~~~~~~~~~~~~~~ + +The Digital TV Frontend kABI defines a driver-internal interface for +registering low-level, hardware specific driver to a hardware independent +frontend layer. It is only of interest for Digital TV device driver writers. +The header file for this API is named ``dvb_frontend.h`` and located in +``include/media/``. + +Demodulator driver +^^^^^^^^^^^^^^^^^^ + +The demodulator driver is responsible for talking with the decoding part of the +hardware. Such driver should implement :c:type:`dvb_frontend_ops`, which +tells what type of digital TV standards are supported, and points to a +series of functions that allow the DVB core to command the hardware via +the code under ``include/media/dvb_frontend.c``. + +A typical example of such struct in a driver ``foo`` is:: + + static struct dvb_frontend_ops foo_ops = { + .delsys = { SYS_DVBT, SYS_DVBT2, SYS_DVBC_ANNEX_A }, + .info = { + .name = "foo DVB-T/T2/C driver", + .caps = FE_CAN_FEC_1_2 | + FE_CAN_FEC_2_3 | + FE_CAN_FEC_3_4 | + FE_CAN_FEC_5_6 | + FE_CAN_FEC_7_8 | + FE_CAN_FEC_AUTO | + FE_CAN_QPSK | + FE_CAN_QAM_16 | + FE_CAN_QAM_32 | + FE_CAN_QAM_64 | + FE_CAN_QAM_128 | + FE_CAN_QAM_256 | + FE_CAN_QAM_AUTO | + FE_CAN_TRANSMISSION_MODE_AUTO | + FE_CAN_GUARD_INTERVAL_AUTO | + FE_CAN_HIERARCHY_AUTO | + FE_CAN_MUTE_TS | + FE_CAN_2G_MODULATION, + .frequency_min = 42000000, /* Hz */ + .frequency_max = 1002000000, /* Hz */ + .symbol_rate_min = 870000, + .symbol_rate_max = 11700000 + }, + .init = foo_init, + .sleep = foo_sleep, + .release = foo_release, + .set_frontend = foo_set_frontend, + .get_frontend = foo_get_frontend, + .read_status = foo_get_status_and_stats, + .tune = foo_tune, + .i2c_gate_ctrl = foo_i2c_gate_ctrl, + .get_frontend_algo = foo_get_algo, + }; + +A typical example of such struct in a driver ``bar`` meant to be used on +Satellite TV reception is:: + + static const struct dvb_frontend_ops bar_ops = { + .delsys = { SYS_DVBS, SYS_DVBS2 }, + .info = { + .name = "Bar DVB-S/S2 demodulator", + .frequency_min = 500000, /* KHz */ + .frequency_max = 2500000, /* KHz */ + .frequency_stepsize = 0, + .symbol_rate_min = 1000000, + .symbol_rate_max = 45000000, + .symbol_rate_tolerance = 500, + .caps = FE_CAN_INVERSION_AUTO | + FE_CAN_FEC_AUTO | + FE_CAN_QPSK, + }, + .init = bar_init, + .sleep = bar_sleep, + .release = bar_release, + .set_frontend = bar_set_frontend, + .get_frontend = bar_get_frontend, + .read_status = bar_get_status_and_stats, + .i2c_gate_ctrl = bar_i2c_gate_ctrl, + .get_frontend_algo = bar_get_algo, + .tune = bar_tune, + + /* Satellite-specific */ + .diseqc_send_master_cmd = bar_send_diseqc_msg, + .diseqc_send_burst = bar_send_burst, + .set_tone = bar_set_tone, + .set_voltage = bar_set_voltage, + }; + +.. note:: + + #) For satellite digital TV standards (DVB-S, DVB-S2, ISDB-S), the + frequencies are specified in kHz, while, for terrestrial and cable + standards, they're specified in Hz. Due to that, if the same frontend + supports both types, you'll need to have two separate + :c:type:`dvb_frontend_ops` structures, one for each standard. + #) The ``.i2c_gate_ctrl`` field is present only when the hardware has + allows controlling an I2C gate (either directly of via some GPIO pin), + in order to remove the tuner from the I2C bus after a channel is + tuned. + #) All new drivers should implement the + :ref:`DVBv5 statistics <dvbv5_stats>` via ``.read_status``. + Yet, there are a number of callbacks meant to get statistics for + signal strength, S/N and UCB. Those are there to provide backward + compatibility with legacy applications that don't support the DVBv5 + API. Implementing those callbacks are optional. Those callbacks may be + removed in the future, after we have all existing drivers supporting + DVBv5 stats. + #) Other callbacks are required for satellite TV standards, in order to + control LNBf and DiSEqC: ``.diseqc_send_master_cmd``, + ``.diseqc_send_burst``, ``.set_tone``, ``.set_voltage``. + +.. |delta| unicode:: U+00394 + +The ``include/media/dvb_frontend.c`` has a kernel thread which is +responsible for tuning the device. It supports multiple algorithms to +detect a channel, as defined at enum :c:func:`dvbfe_algo`. + +The algorithm to be used is obtained via ``.get_frontend_algo``. If the driver +doesn't fill its field at struct :c:type:`dvb_frontend_ops`, it will default to +``DVBFE_ALGO_SW``, meaning that the dvb-core will do a zigzag when tuning, +e. g. it will try first to use the specified center frequency ``f``, +then, it will do ``f`` + |delta|, ``f`` - |delta|, ``f`` + 2 x |delta|, +``f`` - 2 x |delta| and so on. + +If the hardware has internally a some sort of zigzag algorithm, you should +define a ``.get_frontend_algo`` function that would return ``DVBFE_ALGO_HW``. + +.. note:: + + The core frontend support also supports + a third type (``DVBFE_ALGO_CUSTOM``), in order to allow the driver to + define its own hardware-assisted algorithm. Very few hardware need to + use it nowadays. Using ``DVBFE_ALGO_CUSTOM`` require to provide other + function callbacks at struct :c:type:`dvb_frontend_ops`. + +Attaching frontend driver to the bridge driver +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Before using the Digital TV frontend core, the bridge driver should attach +the frontend demod, tuner and SEC devices and call +:c:func:`dvb_register_frontend()`, +in order to register the new frontend at the subsystem. At device +detach/removal, the bridge driver should call +:c:func:`dvb_unregister_frontend()` to +remove the frontend from the core and then :c:func:`dvb_frontend_detach()` +to free the memory allocated by the frontend drivers. + +The drivers should also call :c:func:`dvb_frontend_suspend()` as part of +their handler for the :c:type:`device_driver`.\ ``suspend()``, and +:c:func:`dvb_frontend_resume()` as +part of their handler for :c:type:`device_driver`.\ ``resume()``. + +A few other optional functions are provided to handle some special cases. + +.. _dvbv5_stats: + +Digital TV Frontend statistics +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Introduction +^^^^^^^^^^^^ + +Digital TV frontends provide a range of +:ref:`statistics <frontend-stat-properties>` meant to help tuning the device +and measuring the quality of service. + +For each statistics measurement, the driver should set the type of scale used, +or ``FE_SCALE_NOT_AVAILABLE`` if the statistics is not available on a given +time. Drivers should also provide the number of statistics for each type. +that's usually 1 for most video standards [#f2]_. + +Drivers should initialize each statistic counters with length and +scale at its init code. For example, if the frontend provides signal +strength, it should have, on its init code:: + + struct dtv_frontend_properties *c = &state->fe.dtv_property_cache; + + c->strength.len = 1; + c->strength.stat[0].scale = FE_SCALE_NOT_AVAILABLE; + +And, when the statistics got updated, set the scale:: + + c->strength.stat[0].scale = FE_SCALE_DECIBEL; + c->strength.stat[0].uvalue = strength; + +.. [#f2] For ISDB-T, it may provide both a global statistics and a per-layer + set of statistics. On such cases, len should be equal to 4. The first + value corresponds to the global stat; the other ones to each layer, e. g.: + + - c->cnr.stat[0] for global S/N carrier ratio, + - c->cnr.stat[1] for Layer A S/N carrier ratio, + - c->cnr.stat[2] for layer B S/N carrier ratio, + - c->cnr.stat[3] for layer C S/N carrier ratio. + +.. note:: Please prefer to use ``FE_SCALE_DECIBEL`` instead of + ``FE_SCALE_RELATIVE`` for signal strength and CNR measurements. + +Groups of statistics +^^^^^^^^^^^^^^^^^^^^ + +There are several groups of statistics currently supported: + +Signal strength (:ref:`DTV-STAT-SIGNAL-STRENGTH`) + - Measures the signal strength level at the analog part of the tuner or + demod. + + - Typically obtained from the gain applied to the tuner and/or frontend + in order to detect the carrier. When no carrier is detected, the gain is + at the maximum value (so, strength is on its minimal). + + - As the gain is visible through the set of registers that adjust the gain, + typically, this statistics is always available [#f3]_. + + - Drivers should try to make it available all the times, as these statistics + can be used when adjusting an antenna position and to check for troubles + at the cabling. + + .. [#f3] On a few devices, the gain keeps floating if there is no carrier. + On such devices, strength report should check first if carrier is + detected at the tuner (``FE_HAS_CARRIER``, see :c:type:`fe_status`), + and otherwise return the lowest possible value. + +Carrier Signal to Noise ratio (:ref:`DTV-STAT-CNR`) + - Signal to Noise ratio for the main carrier. + + - Signal to Noise measurement depends on the device. On some hardware, it is + available when the main carrier is detected. On those hardware, CNR + measurement usually comes from the tuner (e. g. after ``FE_HAS_CARRIER``, + see :c:type:`fe_status`). + + On other devices, it requires inner FEC decoding, + as the frontend measures it indirectly from other parameters (e. g. after + ``FE_HAS_VITERBI``, see :c:type:`fe_status`). + + Having it available after inner FEC is more common. + +Bit counts post-FEC (:ref:`DTV-STAT-POST-ERROR-BIT-COUNT` and :ref:`DTV-STAT-POST-TOTAL-BIT-COUNT`) + - Those counters measure the number of bits and bit errors errors after + the forward error correction (FEC) on the inner coding block + (after Viterbi, LDPC or other inner code). + + - Due to its nature, those statistics depend on full coding lock + (e. g. after ``FE_HAS_SYNC`` or after ``FE_HAS_LOCK``, + see :c:type:`fe_status`). + +Bit counts pre-FEC (:ref:`DTV-STAT-PRE-ERROR-BIT-COUNT` and :ref:`DTV-STAT-PRE-TOTAL-BIT-COUNT`) + - Those counters measure the number of bits and bit errors errors before + the forward error correction (FEC) on the inner coding block + (before Viterbi, LDPC or other inner code). + + - Not all frontends provide this kind of statistics. + + - Due to its nature, those statistics depend on inner coding lock (e. g. + after ``FE_HAS_VITERBI``, see :c:type:`fe_status`). + +Block counts (:ref:`DTV-STAT-ERROR-BLOCK-COUNT` and :ref:`DTV-STAT-TOTAL-BLOCK-COUNT`) + - Those counters measure the number of blocks and block errors errors after + the forward error correction (FEC) on the inner coding block + (before Viterbi, LDPC or other inner code). + + - Due to its nature, those statistics depend on full coding lock + (e. g. after ``FE_HAS_SYNC`` or after + ``FE_HAS_LOCK``, see :c:type:`fe_status`). + +.. note:: All counters should be monotonically increased as they're + collected from the hardware. + +A typical example of the logic that handle status and statistics is:: + + static int foo_get_status_and_stats(struct dvb_frontend *fe) + { + struct foo_state *state = fe->demodulator_priv; + struct dtv_frontend_properties *c = &fe->dtv_property_cache; + + int rc; + enum fe_status *status; + + /* Both status and strength are always available */ + rc = foo_read_status(fe, &status); + if (rc < 0) + return rc; + + rc = foo_read_strength(fe); + if (rc < 0) + return rc; + + /* Check if CNR is available */ + if (!(fe->status & FE_HAS_CARRIER)) + return 0; + + rc = foo_read_cnr(fe); + if (rc < 0) + return rc; + + /* Check if pre-BER stats are available */ + if (!(fe->status & FE_HAS_VITERBI)) + return 0; + + rc = foo_get_pre_ber(fe); + if (rc < 0) + return rc; + + /* Check if post-BER stats are available */ + if (!(fe->status & FE_HAS_SYNC)) + return 0; + + rc = foo_get_post_ber(fe); + if (rc < 0) + return rc; + } + + static const struct dvb_frontend_ops ops = { + /* ... */ + .read_status = foo_get_status_and_stats, + }; + +Statistics collection +^^^^^^^^^^^^^^^^^^^^^ + +On almost all frontend hardware, the bit and byte counts are stored by +the hardware after a certain amount of time or after the total bit/block +counter reaches a certain value (usually programmable), for example, on +every 1000 ms or after receiving 1,000,000 bits. + +So, if you read the registers too soon, you'll end by reading the same +value as in the previous reading, causing the monotonic value to be +incremented too often. + +Drivers should take the responsibility to avoid too often reads. That +can be done using two approaches: + +if the driver have a bit that indicates when a collected data is ready +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +Driver should check such bit before making the statistics available. + +An example of such behavior can be found at this code snippet (adapted +from mb86a20s driver's logic):: + + static int foo_get_pre_ber(struct dvb_frontend *fe) + { + struct foo_state *state = fe->demodulator_priv; + struct dtv_frontend_properties *c = &fe->dtv_property_cache; + int rc, bit_error; + + /* Check if the BER measures are already available */ + rc = foo_read_u8(state, 0x54); + if (rc < 0) + return rc; + + if (!rc) + return 0; + + /* Read Bit Error Count */ + bit_error = foo_read_u32(state, 0x55); + if (bit_error < 0) + return bit_error; + + /* Read Total Bit Count */ + rc = foo_read_u32(state, 0x51); + if (rc < 0) + return rc; + + c->pre_bit_error.stat[0].scale = FE_SCALE_COUNTER; + c->pre_bit_error.stat[0].uvalue += bit_error; + c->pre_bit_count.stat[0].scale = FE_SCALE_COUNTER; + c->pre_bit_count.stat[0].uvalue += rc; + + return 0; + } + +If the driver doesn't provide a statistics available check bit +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +A few devices, however, may not provide a way to check if the stats are +available (or the way to check it is unknown). They may not even provide +a way to directly read the total number of bits or blocks. + +On those devices, the driver need to ensure that it won't be reading from +the register too often and/or estimate the total number of bits/blocks. + +On such drivers, a typical routine to get statistics would be like +(adapted from dib8000 driver's logic):: + + struct foo_state { + /* ... */ + + unsigned long per_jiffies_stats; + } + + static int foo_get_pre_ber(struct dvb_frontend *fe) + { + struct foo_state *state = fe->demodulator_priv; + struct dtv_frontend_properties *c = &fe->dtv_property_cache; + int rc, bit_error; + u64 bits; + + /* Check if time for stats was elapsed */ + if (!time_after(jiffies, state->per_jiffies_stats)) + return 0; + + /* Next stat should be collected in 1000 ms */ + state->per_jiffies_stats = jiffies + msecs_to_jiffies(1000); + + /* Read Bit Error Count */ + bit_error = foo_read_u32(state, 0x55); + if (bit_error < 0) + return bit_error; + + /* + * On this particular frontend, there's no register that + * would provide the number of bits per 1000ms sample. So, + * some function would calculate it based on DTV properties + */ + bits = get_number_of_bits_per_1000ms(fe); + + c->pre_bit_error.stat[0].scale = FE_SCALE_COUNTER; + c->pre_bit_error.stat[0].uvalue += bit_error; + c->pre_bit_count.stat[0].scale = FE_SCALE_COUNTER; + c->pre_bit_count.stat[0].uvalue += bits; + + return 0; + } + +Please notice that, on both cases, we're getting the statistics using the +:c:type:`dvb_frontend_ops` ``.read_status`` callback. The rationale is that +the frontend core will automatically call this function periodically +(usually, 3 times per second, when the frontend is locked). + +That warrants that we won't miss to collect a counter and increment the +monotonic stats at the right time. + +Digital TV Frontend functions and types +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: include/media/dvb_frontend.h diff --git a/Documentation/driver-api/media/dtv-net.rst b/Documentation/driver-api/media/dtv-net.rst new file mode 100644 index 000000000000..deb6bffe96bb --- /dev/null +++ b/Documentation/driver-api/media/dtv-net.rst @@ -0,0 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Digital TV Network kABI +----------------------- + +.. kernel-doc:: include/media/dvb_net.h diff --git a/Documentation/driver-api/media/index.rst b/Documentation/driver-api/media/index.rst new file mode 100644 index 000000000000..328350924853 --- /dev/null +++ b/Documentation/driver-api/media/index.rst @@ -0,0 +1,54 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: <isonum.txt> + +=================================== +Media subsystem kernel internal API +=================================== + +This section contains usage information about media subsystem and +its supported drivers. + +Please see: + +- :doc:`/admin-guide/media/index` + for usage information about media subsystem and supported drivers; + +- :doc:`/userspace-api/media/index` + for the userspace APIs used on media devices. + + +.. only:: html + + .. class:: toc-title + + Table of Contents + +.. toctree:: + :maxdepth: 5 + :numbered: + + v4l2-core + dtv-core + rc-core + mc-core + cec-core + csi2 + + drivers/index + +**Copyright** |copy| 2009-2020 : LinuxTV Developers + +:: + + This documentation is free software; you can redistribute it and/or modify it + under the terms of the GNU General Public License as published by the Free + Software Foundation; either version 2 of the License, or (at your option) any + later version. + + This program is distributed in the hope that it will be useful, but WITHOUT + ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + more details. + + For more details see the file COPYING in the source distribution of Linux. diff --git a/Documentation/driver-api/media/mc-core.rst b/Documentation/driver-api/media/mc-core.rst new file mode 100644 index 000000000000..05bba0b61748 --- /dev/null +++ b/Documentation/driver-api/media/mc-core.rst @@ -0,0 +1,309 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Media Controller devices +------------------------ + +Media Controller +~~~~~~~~~~~~~~~~ + +The media controller userspace API is documented in +:ref:`the Media Controller uAPI book <media_controller>`. This document focus +on the kernel-side implementation of the media framework. + +Abstract media device model +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Discovering a device internal topology, and configuring it at runtime, is one +of the goals of the media framework. To achieve this, hardware devices are +modelled as an oriented graph of building blocks called entities connected +through pads. + +An entity is a basic media hardware building block. It can correspond to +a large variety of logical blocks such as physical hardware devices +(CMOS sensor for instance), logical hardware devices (a building block +in a System-on-Chip image processing pipeline), DMA channels or physical +connectors. + +A pad is a connection endpoint through which an entity can interact with +other entities. Data (not restricted to video) produced by an entity +flows from the entity's output to one or more entity inputs. Pads should +not be confused with physical pins at chip boundaries. + +A link is a point-to-point oriented connection between two pads, either +on the same entity or on different entities. Data flows from a source +pad to a sink pad. + +Media device +^^^^^^^^^^^^ + +A media device is represented by a struct :c:type:`media_device` +instance, defined in ``include/media/media-device.h``. +Allocation of the structure is handled by the media device driver, usually by +embedding the :c:type:`media_device` instance in a larger driver-specific +structure. + +Drivers register media device instances by calling +:c:func:`__media_device_register()` via the macro ``media_device_register()`` +and unregistered by calling :c:func:`media_device_unregister()`. + +Entities +^^^^^^^^ + +Entities are represented by a struct :c:type:`media_entity` +instance, defined in ``include/media/media-entity.h``. The structure is usually +embedded into a higher-level structure, such as +:c:type:`v4l2_subdev` or :c:type:`video_device` +instances, although drivers can allocate entities directly. + +Drivers initialize entity pads by calling +:c:func:`media_entity_pads_init()`. + +Drivers register entities with a media device by calling +:c:func:`media_device_register_entity()` +and unregistered by calling +:c:func:`media_device_unregister_entity()`. + +Interfaces +^^^^^^^^^^ + +Interfaces are represented by a +struct :c:type:`media_interface` instance, defined in +``include/media/media-entity.h``. Currently, only one type of interface is +defined: a device node. Such interfaces are represented by a +struct :c:type:`media_intf_devnode`. + +Drivers initialize and create device node interfaces by calling +:c:func:`media_devnode_create()` +and remove them by calling: +:c:func:`media_devnode_remove()`. + +Pads +^^^^ +Pads are represented by a struct :c:type:`media_pad` instance, +defined in ``include/media/media-entity.h``. Each entity stores its pads in +a pads array managed by the entity driver. Drivers usually embed the array in +a driver-specific structure. + +Pads are identified by their entity and their 0-based index in the pads +array. + +Both information are stored in the struct :c:type:`media_pad`, +making the struct :c:type:`media_pad` pointer the canonical way +to store and pass link references. + +Pads have flags that describe the pad capabilities and state. + +``MEDIA_PAD_FL_SINK`` indicates that the pad supports sinking data. +``MEDIA_PAD_FL_SOURCE`` indicates that the pad supports sourcing data. + +.. note:: + + One and only one of ``MEDIA_PAD_FL_SINK`` or ``MEDIA_PAD_FL_SOURCE`` must + be set for each pad. + +Links +^^^^^ + +Links are represented by a struct :c:type:`media_link` instance, +defined in ``include/media/media-entity.h``. There are two types of links: + +**1. pad to pad links**: + +Associate two entities via their PADs. Each entity has a list that points +to all links originating at or targeting any of its pads. +A given link is thus stored twice, once in the source entity and once in +the target entity. + +Drivers create pad to pad links by calling: +:c:func:`media_create_pad_link()` and remove with +:c:func:`media_entity_remove_links()`. + +**2. interface to entity links**: + +Associate one interface to a Link. + +Drivers create interface to entity links by calling: +:c:func:`media_create_intf_link()` and remove with +:c:func:`media_remove_intf_links()`. + +.. note:: + + Links can only be created after having both ends already created. + +Links have flags that describe the link capabilities and state. The +valid values are described at :c:func:`media_create_pad_link()` and +:c:func:`media_create_intf_link()`. + +Graph traversal +^^^^^^^^^^^^^^^ + +The media framework provides APIs to iterate over entities in a graph. + +To iterate over all entities belonging to a media device, drivers can use +the media_device_for_each_entity macro, defined in +``include/media/media-device.h``. + +.. code-block:: c + + struct media_entity *entity; + + media_device_for_each_entity(entity, mdev) { + // entity will point to each entity in turn + ... + } + +Drivers might also need to iterate over all entities in a graph that can be +reached only through enabled links starting at a given entity. The media +framework provides a depth-first graph traversal API for that purpose. + +.. note:: + + Graphs with cycles (whether directed or undirected) are **NOT** + supported by the graph traversal API. To prevent infinite loops, the graph + traversal code limits the maximum depth to ``MEDIA_ENTITY_ENUM_MAX_DEPTH``, + currently defined as 16. + +Drivers initiate a graph traversal by calling +:c:func:`media_graph_walk_start()` + +The graph structure, provided by the caller, is initialized to start graph +traversal at the given entity. + +Drivers can then retrieve the next entity by calling +:c:func:`media_graph_walk_next()` + +When the graph traversal is complete the function will return ``NULL``. + +Graph traversal can be interrupted at any moment. No cleanup function call +is required and the graph structure can be freed normally. + +Helper functions can be used to find a link between two given pads, or a pad +connected to another pad through an enabled link +:c:func:`media_entity_find_link()` and +:c:func:`media_entity_remote_pad()`. + +Use count and power handling +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Due to the wide differences between drivers regarding power management +needs, the media controller does not implement power management. However, +the struct :c:type:`media_entity` includes a ``use_count`` +field that media drivers +can use to track the number of users of every entity for power management +needs. + +The :c:type:`media_entity<media_entity>`.\ ``use_count`` field is owned by +media drivers and must not be +touched by entity drivers. Access to the field must be protected by the +:c:type:`media_device`.\ ``graph_mutex`` lock. + +Links setup +^^^^^^^^^^^ + +Link properties can be modified at runtime by calling +:c:func:`media_entity_setup_link()`. + +Pipelines and media streams +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When starting streaming, drivers must notify all entities in the pipeline to +prevent link states from being modified during streaming by calling +:c:func:`media_pipeline_start()`. + +The function will mark all entities connected to the given entity through +enabled links, either directly or indirectly, as streaming. + +The struct :c:type:`media_pipeline` instance pointed to by +the pipe argument will be stored in every entity in the pipeline. +Drivers should embed the struct :c:type:`media_pipeline` +in higher-level pipeline structures and can then access the +pipeline through the struct :c:type:`media_entity` +pipe field. + +Calls to :c:func:`media_pipeline_start()` can be nested. +The pipeline pointer must be identical for all nested calls to the function. + +:c:func:`media_pipeline_start()` may return an error. In that case, +it will clean up any of the changes it did by itself. + +When stopping the stream, drivers must notify the entities with +:c:func:`media_pipeline_stop()`. + +If multiple calls to :c:func:`media_pipeline_start()` have been +made the same number of :c:func:`media_pipeline_stop()` calls +are required to stop streaming. +The :c:type:`media_entity`.\ ``pipe`` field is reset to ``NULL`` on the last +nested stop call. + +Link configuration will fail with ``-EBUSY`` by default if either end of the +link is a streaming entity. Links that can be modified while streaming must +be marked with the ``MEDIA_LNK_FL_DYNAMIC`` flag. + +If other operations need to be disallowed on streaming entities (such as +changing entities configuration parameters) drivers can explicitly check the +media_entity stream_count field to find out if an entity is streaming. This +operation must be done with the media_device graph_mutex held. + +Link validation +^^^^^^^^^^^^^^^ + +Link validation is performed by :c:func:`media_pipeline_start()` +for any entity which has sink pads in the pipeline. The +:c:type:`media_entity`.\ ``link_validate()`` callback is used for that +purpose. In ``link_validate()`` callback, entity driver should check +that the properties of the source pad of the connected entity and its own +sink pad match. It is up to the type of the entity (and in the end, the +properties of the hardware) what matching actually means. + +Subsystems should facilitate link validation by providing subsystem specific +helper functions to provide easy access for commonly needed information, and +in the end provide a way to use driver-specific callbacks. + +Media Controller Device Allocator API +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When the media device belongs to more than one driver, the shared media +device is allocated with the shared struct device as the key for look ups. + +The shared media device should stay in registered state until the last +driver unregisters it. In addition, the media device should be released when +all the references are released. Each driver gets a reference to the media +device during probe, when it allocates the media device. If media device is +already allocated, the allocate API bumps up the refcount and returns the +existing media device. The driver puts the reference back in its disconnect +routine when it calls :c:func:`media_device_delete()`. + +The media device is unregistered and cleaned up from the kref put handler to +ensure that the media device stays in registered state until the last driver +unregisters the media device. + +**Driver Usage** + +Drivers should use the appropriate media-core routines to manage the shared +media device life-time handling the two states: +1. allocate -> register -> delete +2. get reference to already registered device -> delete + +call :c:func:`media_device_delete()` routine to make sure the shared media +device delete is handled correctly. + +**driver probe:** +Call :c:func:`media_device_usb_allocate()` to allocate or get a reference +Call :c:func:`media_device_register()`, if media devnode isn't registered + +**driver disconnect:** +Call :c:func:`media_device_delete()` to free the media_device. Freeing is +handled by the kref put handler. + +API Definitions +^^^^^^^^^^^^^^^ + +.. kernel-doc:: include/media/media-device.h + +.. kernel-doc:: include/media/media-devnode.h + +.. kernel-doc:: include/media/media-entity.h + +.. kernel-doc:: include/media/media-request.h + +.. kernel-doc:: include/media/media-dev-allocator.h diff --git a/Documentation/driver-api/media/rc-core.rst b/Documentation/driver-api/media/rc-core.rst new file mode 100644 index 000000000000..53f5e643b6e9 --- /dev/null +++ b/Documentation/driver-api/media/rc-core.rst @@ -0,0 +1,88 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Remote Controller devices +------------------------- + +Remote Controller core +~~~~~~~~~~~~~~~~~~~~~~ + +The remote controller core implements infrastructure to receive and send +remote controller keyboard keystrokes and mouse events. + +Every time a key is pressed on a remote controller, a scan code is produced. +Also, on most hardware, keeping a key pressed for more than a few dozens of +milliseconds produce a repeat key event. That's somewhat similar to what +a normal keyboard or mouse is handled internally on Linux\ [#f1]_. So, the +remote controller core is implemented on the top of the linux input/evdev +interface. + +.. [#f1] + + The main difference is that, on keyboard events, the keyboard controller + produces one event for a key press and another one for key release. On + infrared-based remote controllers, there's no key release event. Instead, + an extra code is produced to indicate key repeats. + +However, most of the remote controllers use infrared (IR) to transmit signals. +As there are several protocols used to modulate infrared signals, one +important part of the core is dedicated to adjust the driver and the core +system to support the infrared protocol used by the emitter. + +The infrared transmission is done by blinking a infrared emitter using a +carrier. The carrier can be switched on or off by the IR transmitter +hardware. When the carrier is switched on, it is called *PULSE*. +When the carrier is switched off, it is called *SPACE*. + +In other words, a typical IR transmission can be viewed as a sequence of +*PULSE* and *SPACE* events, each with a given duration. + +The carrier parameters (frequency, duty cycle) and the intervals for +*PULSE* and *SPACE* events depend on the protocol. +For example, the NEC protocol uses a carrier of 38kHz, and transmissions +start with a 9ms *PULSE* and a 4.5ms SPACE. It then transmits 16 bits of +scan code, being 8 bits for address (usually it is a fixed number for a +given remote controller), followed by 8 bits of code. A bit "1" is modulated +with 560µs *PULSE* followed by 1690µs *SPACE* and a bit "0" is modulated +with 560µs *PULSE* followed by 560µs *SPACE*. + +At receiver, a simple low-pass filter can be used to convert the received +signal in a sequence of *PULSE/SPACE* events, filtering out the carrier +frequency. Due to that, the receiver doesn't care about the carrier's +actual frequency parameters: all it has to do is to measure the amount +of time it receives *PULSE/SPACE* events. +So, a simple IR receiver hardware will just provide a sequence of timings +for those events to the Kernel. The drivers for hardware with such kind of +receivers are identified by ``RC_DRIVER_IR_RAW``, as defined by +:c:type:`rc_driver_type`\ [#f2]_. Other hardware come with a +microcontroller that decode the *PULSE/SPACE* sequence and return scan +codes to the Kernel. Such kind of receivers are identified +by ``RC_DRIVER_SCANCODE``. + +.. [#f2] + + The RC core also supports devices that have just IR emitters, + without any receivers. Right now, all such devices work only in + raw TX mode. Such kind of hardware is identified as + ``RC_DRIVER_IR_RAW_TX``. + +When the RC core receives events produced by ``RC_DRIVER_IR_RAW`` IR +receivers, it needs to decode the IR protocol, in order to obtain the +corresponding scan code. The protocols supported by the RC core are +defined at enum :c:type:`rc_proto`. + +When the RC code receives a scan code (either directly, by a driver +of the type ``RC_DRIVER_SCANCODE``, or via its IR decoders), it needs +to convert into a Linux input event code. This is done via a mapping +table. + +The Kernel has support for mapping tables available on most media +devices. It also supports loading a table in runtime, via some +sysfs nodes. See the :ref:`RC userspace API <Remote_controllers_Intro>` +for more details. + +Remote controller data structures and functions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. kernel-doc:: include/media/rc-core.h + +.. kernel-doc:: include/media/rc-map.h diff --git a/Documentation/driver-api/media/v4l2-async.rst b/Documentation/driver-api/media/v4l2-async.rst new file mode 100644 index 000000000000..3422330b3b1f --- /dev/null +++ b/Documentation/driver-api/media/v4l2-async.rst @@ -0,0 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + +V4L2 async kAPI +^^^^^^^^^^^^^^^ +.. kernel-doc:: include/media/v4l2-async.h diff --git a/Documentation/driver-api/media/v4l2-clocks.rst b/Documentation/driver-api/media/v4l2-clocks.rst new file mode 100644 index 000000000000..5c22eecab7ba --- /dev/null +++ b/Documentation/driver-api/media/v4l2-clocks.rst @@ -0,0 +1,31 @@ +.. SPDX-License-Identifier: GPL-2.0 + +V4L2 clocks +----------- + +.. attention:: + + This is a temporary API and it shall be replaced by the generic + clock API, when the latter becomes widely available. + +Many subdevices, like camera sensors, TV decoders and encoders, need a clock +signal to be supplied by the system. Often this clock is supplied by the +respective bridge device. The Linux kernel provides a Common Clock Framework for +this purpose. However, it is not (yet) available on all architectures. Besides, +the nature of the multi-functional (clock, data + synchronisation, I2C control) +connection of subdevices to the system might impose special requirements on the +clock API usage. E.g. V4L2 has to support clock provider driver unregistration +while a subdevice driver is holding a reference to the clock. For these reasons +a V4L2 clock helper API has been developed and is provided to bridge and +subdevice drivers. + +The API consists of two parts: two functions to register and unregister a V4L2 +clock source: v4l2_clk_register() and v4l2_clk_unregister() and calls to control +a clock object, similar to the respective generic clock API calls: +v4l2_clk_get(), v4l2_clk_put(), v4l2_clk_enable(), v4l2_clk_disable(), +v4l2_clk_get_rate(), and v4l2_clk_set_rate(). Clock suppliers have to provide +clock operations that will be called when clock users invoke respective API +methods. + +It is expected that once the CCF becomes available on all relevant +architectures this API will be removed. diff --git a/Documentation/driver-api/media/v4l2-common.rst b/Documentation/driver-api/media/v4l2-common.rst new file mode 100644 index 000000000000..b1e70eb56aa4 --- /dev/null +++ b/Documentation/driver-api/media/v4l2-common.rst @@ -0,0 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 + +V4L2 common functions and data structures +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. kernel-doc:: include/media/v4l2-common.h + +.. kernel-doc:: include/media/v4l2-ioctl.h diff --git a/Documentation/driver-api/media/v4l2-controls.rst b/Documentation/driver-api/media/v4l2-controls.rst new file mode 100644 index 000000000000..5129019afb49 --- /dev/null +++ b/Documentation/driver-api/media/v4l2-controls.rst @@ -0,0 +1,823 @@ +.. SPDX-License-Identifier: GPL-2.0 + +V4L2 Controls +============= + +Introduction +------------ + +The V4L2 control API seems simple enough, but quickly becomes very hard to +implement correctly in drivers. But much of the code needed to handle controls +is actually not driver specific and can be moved to the V4L core framework. + +After all, the only part that a driver developer is interested in is: + +1) How do I add a control? +2) How do I set the control's value? (i.e. s_ctrl) + +And occasionally: + +3) How do I get the control's value? (i.e. g_volatile_ctrl) +4) How do I validate the user's proposed control value? (i.e. try_ctrl) + +All the rest is something that can be done centrally. + +The control framework was created in order to implement all the rules of the +V4L2 specification with respect to controls in a central place. And to make +life as easy as possible for the driver developer. + +Note that the control framework relies on the presence of a struct +:c:type:`v4l2_device` for V4L2 drivers and struct :c:type:`v4l2_subdev` for +sub-device drivers. + + +Objects in the framework +------------------------ + +There are two main objects: + +The :c:type:`v4l2_ctrl` object describes the control properties and keeps +track of the control's value (both the current value and the proposed new +value). + +:c:type:`v4l2_ctrl_handler` is the object that keeps track of controls. It +maintains a list of v4l2_ctrl objects that it owns and another list of +references to controls, possibly to controls owned by other handlers. + + +Basic usage for V4L2 and sub-device drivers +------------------------------------------- + +1) Prepare the driver: + +.. code-block:: c + + #include <media/v4l2-ctrls.h> + +1.1) Add the handler to your driver's top-level struct: + +For V4L2 drivers: + +.. code-block:: c + + struct foo_dev { + ... + struct v4l2_device v4l2_dev; + ... + struct v4l2_ctrl_handler ctrl_handler; + ... + }; + +For sub-device drivers: + +.. code-block:: c + + struct foo_dev { + ... + struct v4l2_subdev sd; + ... + struct v4l2_ctrl_handler ctrl_handler; + ... + }; + +1.2) Initialize the handler: + +.. code-block:: c + + v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls); + +The second argument is a hint telling the function how many controls this +handler is expected to handle. It will allocate a hashtable based on this +information. It is a hint only. + +1.3) Hook the control handler into the driver: + +For V4L2 drivers: + +.. code-block:: c + + foo->v4l2_dev.ctrl_handler = &foo->ctrl_handler; + +For sub-device drivers: + +.. code-block:: c + + foo->sd.ctrl_handler = &foo->ctrl_handler; + +1.4) Clean up the handler at the end: + +.. code-block:: c + + v4l2_ctrl_handler_free(&foo->ctrl_handler); + + +2) Add controls: + +You add non-menu controls by calling :c:func:`v4l2_ctrl_new_std`: + +.. code-block:: c + + struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl, + const struct v4l2_ctrl_ops *ops, + u32 id, s32 min, s32 max, u32 step, s32 def); + +Menu and integer menu controls are added by calling +:c:func:`v4l2_ctrl_new_std_menu`: + +.. code-block:: c + + struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl, + const struct v4l2_ctrl_ops *ops, + u32 id, s32 max, s32 skip_mask, s32 def); + +Menu controls with a driver specific menu are added by calling +:c:func:`v4l2_ctrl_new_std_menu_items`: + +.. code-block:: c + + struct v4l2_ctrl *v4l2_ctrl_new_std_menu_items( + struct v4l2_ctrl_handler *hdl, + const struct v4l2_ctrl_ops *ops, u32 id, s32 max, + s32 skip_mask, s32 def, const char * const *qmenu); + +Standard compound controls can be added by calling +:c:func:`v4l2_ctrl_new_std_compound`: + +.. code-block:: c + + struct v4l2_ctrl *v4l2_ctrl_new_std_compound(struct v4l2_ctrl_handler *hdl, + const struct v4l2_ctrl_ops *ops, u32 id, + const union v4l2_ctrl_ptr p_def); + +Integer menu controls with a driver specific menu can be added by calling +:c:func:`v4l2_ctrl_new_int_menu`: + +.. code-block:: c + + struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl, + const struct v4l2_ctrl_ops *ops, + u32 id, s32 max, s32 def, const s64 *qmenu_int); + +These functions are typically called right after the +:c:func:`v4l2_ctrl_handler_init`: + +.. code-block:: c + + static const s64 exp_bias_qmenu[] = { + -2, -1, 0, 1, 2 + }; + static const char * const test_pattern[] = { + "Disabled", + "Vertical Bars", + "Solid Black", + "Solid White", + }; + + v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls); + v4l2_ctrl_new_std(&foo->ctrl_handler, &foo_ctrl_ops, + V4L2_CID_BRIGHTNESS, 0, 255, 1, 128); + v4l2_ctrl_new_std(&foo->ctrl_handler, &foo_ctrl_ops, + V4L2_CID_CONTRAST, 0, 255, 1, 128); + v4l2_ctrl_new_std_menu(&foo->ctrl_handler, &foo_ctrl_ops, + V4L2_CID_POWER_LINE_FREQUENCY, + V4L2_CID_POWER_LINE_FREQUENCY_60HZ, 0, + V4L2_CID_POWER_LINE_FREQUENCY_DISABLED); + v4l2_ctrl_new_int_menu(&foo->ctrl_handler, &foo_ctrl_ops, + V4L2_CID_EXPOSURE_BIAS, + ARRAY_SIZE(exp_bias_qmenu) - 1, + ARRAY_SIZE(exp_bias_qmenu) / 2 - 1, + exp_bias_qmenu); + v4l2_ctrl_new_std_menu_items(&foo->ctrl_handler, &foo_ctrl_ops, + V4L2_CID_TEST_PATTERN, ARRAY_SIZE(test_pattern) - 1, 0, + 0, test_pattern); + ... + if (foo->ctrl_handler.error) { + int err = foo->ctrl_handler.error; + + v4l2_ctrl_handler_free(&foo->ctrl_handler); + return err; + } + +The :c:func:`v4l2_ctrl_new_std` function returns the v4l2_ctrl pointer to +the new control, but if you do not need to access the pointer outside the +control ops, then there is no need to store it. + +The :c:func:`v4l2_ctrl_new_std` function will fill in most fields based on +the control ID except for the min, max, step and default values. These are +passed in the last four arguments. These values are driver specific while +control attributes like type, name, flags are all global. The control's +current value will be set to the default value. + +The :c:func:`v4l2_ctrl_new_std_menu` function is very similar but it is +used for menu controls. There is no min argument since that is always 0 for +menu controls, and instead of a step there is a skip_mask argument: if bit +X is 1, then menu item X is skipped. + +The :c:func:`v4l2_ctrl_new_int_menu` function creates a new standard +integer menu control with driver-specific items in the menu. It differs +from v4l2_ctrl_new_std_menu in that it doesn't have the mask argument and +takes as the last argument an array of signed 64-bit integers that form an +exact menu item list. + +The :c:func:`v4l2_ctrl_new_std_menu_items` function is very similar to +v4l2_ctrl_new_std_menu but takes an extra parameter qmenu, which is the +driver specific menu for an otherwise standard menu control. A good example +for this control is the test pattern control for capture/display/sensors +devices that have the capability to generate test patterns. These test +patterns are hardware specific, so the contents of the menu will vary from +device to device. + +Note that if something fails, the function will return NULL or an error and +set ctrl_handler->error to the error code. If ctrl_handler->error was already +set, then it will just return and do nothing. This is also true for +v4l2_ctrl_handler_init if it cannot allocate the internal data structure. + +This makes it easy to init the handler and just add all controls and only check +the error code at the end. Saves a lot of repetitive error checking. + +It is recommended to add controls in ascending control ID order: it will be +a bit faster that way. + +3) Optionally force initial control setup: + +.. code-block:: c + + v4l2_ctrl_handler_setup(&foo->ctrl_handler); + +This will call s_ctrl for all controls unconditionally. Effectively this +initializes the hardware to the default control values. It is recommended +that you do this as this ensures that both the internal data structures and +the hardware are in sync. + +4) Finally: implement the :c:type:`v4l2_ctrl_ops` + +.. code-block:: c + + static const struct v4l2_ctrl_ops foo_ctrl_ops = { + .s_ctrl = foo_s_ctrl, + }; + +Usually all you need is s_ctrl: + +.. code-block:: c + + static int foo_s_ctrl(struct v4l2_ctrl *ctrl) + { + struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler); + + switch (ctrl->id) { + case V4L2_CID_BRIGHTNESS: + write_reg(0x123, ctrl->val); + break; + case V4L2_CID_CONTRAST: + write_reg(0x456, ctrl->val); + break; + } + return 0; + } + +The control ops are called with the v4l2_ctrl pointer as argument. +The new control value has already been validated, so all you need to do is +to actually update the hardware registers. + +You're done! And this is sufficient for most of the drivers we have. No need +to do any validation of control values, or implement QUERYCTRL, QUERY_EXT_CTRL +and QUERYMENU. And G/S_CTRL as well as G/TRY/S_EXT_CTRLS are automatically supported. + + +.. note:: + + The remainder sections deal with more advanced controls topics and scenarios. + In practice the basic usage as described above is sufficient for most drivers. + + +Inheriting Sub-device Controls +------------------------------ + +When a sub-device is registered with a V4L2 driver by calling +v4l2_device_register_subdev() and the ctrl_handler fields of both v4l2_subdev +and v4l2_device are set, then the controls of the subdev will become +automatically available in the V4L2 driver as well. If the subdev driver +contains controls that already exist in the V4L2 driver, then those will be +skipped (so a V4L2 driver can always override a subdev control). + +What happens here is that v4l2_device_register_subdev() calls +v4l2_ctrl_add_handler() adding the controls of the subdev to the controls +of v4l2_device. + + +Accessing Control Values +------------------------ + +The following union is used inside the control framework to access control +values: + +.. code-block:: c + + union v4l2_ctrl_ptr { + s32 *p_s32; + s64 *p_s64; + char *p_char; + void *p; + }; + +The v4l2_ctrl struct contains these fields that can be used to access both +current and new values: + +.. code-block:: c + + s32 val; + struct { + s32 val; + } cur; + + + union v4l2_ctrl_ptr p_new; + union v4l2_ctrl_ptr p_cur; + +If the control has a simple s32 type type, then: + +.. code-block:: c + + &ctrl->val == ctrl->p_new.p_s32 + &ctrl->cur.val == ctrl->p_cur.p_s32 + +For all other types use ctrl->p_cur.p<something>. Basically the val +and cur.val fields can be considered an alias since these are used so often. + +Within the control ops you can freely use these. The val and cur.val speak for +themselves. The p_char pointers point to character buffers of length +ctrl->maximum + 1, and are always 0-terminated. + +Unless the control is marked volatile the p_cur field points to the the +current cached control value. When you create a new control this value is made +identical to the default value. After calling v4l2_ctrl_handler_setup() this +value is passed to the hardware. It is generally a good idea to call this +function. + +Whenever a new value is set that new value is automatically cached. This means +that most drivers do not need to implement the g_volatile_ctrl() op. The +exception is for controls that return a volatile register such as a signal +strength read-out that changes continuously. In that case you will need to +implement g_volatile_ctrl like this: + +.. code-block:: c + + static int foo_g_volatile_ctrl(struct v4l2_ctrl *ctrl) + { + switch (ctrl->id) { + case V4L2_CID_BRIGHTNESS: + ctrl->val = read_reg(0x123); + break; + } + } + +Note that you use the 'new value' union as well in g_volatile_ctrl. In general +controls that need to implement g_volatile_ctrl are read-only controls. If they +are not, a V4L2_EVENT_CTRL_CH_VALUE will not be generated when the control +changes. + +To mark a control as volatile you have to set V4L2_CTRL_FLAG_VOLATILE: + +.. code-block:: c + + ctrl = v4l2_ctrl_new_std(&sd->ctrl_handler, ...); + if (ctrl) + ctrl->flags |= V4L2_CTRL_FLAG_VOLATILE; + +For try/s_ctrl the new values (i.e. as passed by the user) are filled in and +you can modify them in try_ctrl or set them in s_ctrl. The 'cur' union +contains the current value, which you can use (but not change!) as well. + +If s_ctrl returns 0 (OK), then the control framework will copy the new final +values to the 'cur' union. + +While in g_volatile/s/try_ctrl you can access the value of all controls owned +by the same handler since the handler's lock is held. If you need to access +the value of controls owned by other handlers, then you have to be very careful +not to introduce deadlocks. + +Outside of the control ops you have to go through to helper functions to get +or set a single control value safely in your driver: + +.. code-block:: c + + s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl); + int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val); + +These functions go through the control framework just as VIDIOC_G/S_CTRL ioctls +do. Don't use these inside the control ops g_volatile/s/try_ctrl, though, that +will result in a deadlock since these helpers lock the handler as well. + +You can also take the handler lock yourself: + +.. code-block:: c + + mutex_lock(&state->ctrl_handler.lock); + pr_info("String value is '%s'\n", ctrl1->p_cur.p_char); + pr_info("Integer value is '%s'\n", ctrl2->cur.val); + mutex_unlock(&state->ctrl_handler.lock); + + +Menu Controls +------------- + +The v4l2_ctrl struct contains this union: + +.. code-block:: c + + union { + u32 step; + u32 menu_skip_mask; + }; + +For menu controls menu_skip_mask is used. What it does is that it allows you +to easily exclude certain menu items. This is used in the VIDIOC_QUERYMENU +implementation where you can return -EINVAL if a certain menu item is not +present. Note that VIDIOC_QUERYCTRL always returns a step value of 1 for +menu controls. + +A good example is the MPEG Audio Layer II Bitrate menu control where the +menu is a list of standardized possible bitrates. But in practice hardware +implementations will only support a subset of those. By setting the skip +mask you can tell the framework which menu items should be skipped. Setting +it to 0 means that all menu items are supported. + +You set this mask either through the v4l2_ctrl_config struct for a custom +control, or by calling v4l2_ctrl_new_std_menu(). + + +Custom Controls +--------------- + +Driver specific controls can be created using v4l2_ctrl_new_custom(): + +.. code-block:: c + + static const struct v4l2_ctrl_config ctrl_filter = { + .ops = &ctrl_custom_ops, + .id = V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER, + .name = "Spatial Filter", + .type = V4L2_CTRL_TYPE_INTEGER, + .flags = V4L2_CTRL_FLAG_SLIDER, + .max = 15, + .step = 1, + }; + + ctrl = v4l2_ctrl_new_custom(&foo->ctrl_handler, &ctrl_filter, NULL); + +The last argument is the priv pointer which can be set to driver-specific +private data. + +The v4l2_ctrl_config struct also has a field to set the is_private flag. + +If the name field is not set, then the framework will assume this is a standard +control and will fill in the name, type and flags fields accordingly. + + +Active and Grabbed Controls +--------------------------- + +If you get more complex relationships between controls, then you may have to +activate and deactivate controls. For example, if the Chroma AGC control is +on, then the Chroma Gain control is inactive. That is, you may set it, but +the value will not be used by the hardware as long as the automatic gain +control is on. Typically user interfaces can disable such input fields. + +You can set the 'active' status using v4l2_ctrl_activate(). By default all +controls are active. Note that the framework does not check for this flag. +It is meant purely for GUIs. The function is typically called from within +s_ctrl. + +The other flag is the 'grabbed' flag. A grabbed control means that you cannot +change it because it is in use by some resource. Typical examples are MPEG +bitrate controls that cannot be changed while capturing is in progress. + +If a control is set to 'grabbed' using v4l2_ctrl_grab(), then the framework +will return -EBUSY if an attempt is made to set this control. The +v4l2_ctrl_grab() function is typically called from the driver when it +starts or stops streaming. + + +Control Clusters +---------------- + +By default all controls are independent from the others. But in more +complex scenarios you can get dependencies from one control to another. +In that case you need to 'cluster' them: + +.. code-block:: c + + struct foo { + struct v4l2_ctrl_handler ctrl_handler; + #define AUDIO_CL_VOLUME (0) + #define AUDIO_CL_MUTE (1) + struct v4l2_ctrl *audio_cluster[2]; + ... + }; + + state->audio_cluster[AUDIO_CL_VOLUME] = + v4l2_ctrl_new_std(&state->ctrl_handler, ...); + state->audio_cluster[AUDIO_CL_MUTE] = + v4l2_ctrl_new_std(&state->ctrl_handler, ...); + v4l2_ctrl_cluster(ARRAY_SIZE(state->audio_cluster), state->audio_cluster); + +From now on whenever one or more of the controls belonging to the same +cluster is set (or 'gotten', or 'tried'), only the control ops of the first +control ('volume' in this example) is called. You effectively create a new +composite control. Similar to how a 'struct' works in C. + +So when s_ctrl is called with V4L2_CID_AUDIO_VOLUME as argument, you should set +all two controls belonging to the audio_cluster: + +.. code-block:: c + + static int foo_s_ctrl(struct v4l2_ctrl *ctrl) + { + struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler); + + switch (ctrl->id) { + case V4L2_CID_AUDIO_VOLUME: { + struct v4l2_ctrl *mute = ctrl->cluster[AUDIO_CL_MUTE]; + + write_reg(0x123, mute->val ? 0 : ctrl->val); + break; + } + case V4L2_CID_CONTRAST: + write_reg(0x456, ctrl->val); + break; + } + return 0; + } + +In the example above the following are equivalent for the VOLUME case: + +.. code-block:: c + + ctrl == ctrl->cluster[AUDIO_CL_VOLUME] == state->audio_cluster[AUDIO_CL_VOLUME] + ctrl->cluster[AUDIO_CL_MUTE] == state->audio_cluster[AUDIO_CL_MUTE] + +In practice using cluster arrays like this becomes very tiresome. So instead +the following equivalent method is used: + +.. code-block:: c + + struct { + /* audio cluster */ + struct v4l2_ctrl *volume; + struct v4l2_ctrl *mute; + }; + +The anonymous struct is used to clearly 'cluster' these two control pointers, +but it serves no other purpose. The effect is the same as creating an +array with two control pointers. So you can just do: + +.. code-block:: c + + state->volume = v4l2_ctrl_new_std(&state->ctrl_handler, ...); + state->mute = v4l2_ctrl_new_std(&state->ctrl_handler, ...); + v4l2_ctrl_cluster(2, &state->volume); + +And in foo_s_ctrl you can use these pointers directly: state->mute->val. + +Note that controls in a cluster may be NULL. For example, if for some +reason mute was never added (because the hardware doesn't support that +particular feature), then mute will be NULL. So in that case we have a +cluster of 2 controls, of which only 1 is actually instantiated. The +only restriction is that the first control of the cluster must always be +present, since that is the 'master' control of the cluster. The master +control is the one that identifies the cluster and that provides the +pointer to the v4l2_ctrl_ops struct that is used for that cluster. + +Obviously, all controls in the cluster array must be initialized to either +a valid control or to NULL. + +In rare cases you might want to know which controls of a cluster actually +were set explicitly by the user. For this you can check the 'is_new' flag of +each control. For example, in the case of a volume/mute cluster the 'is_new' +flag of the mute control would be set if the user called VIDIOC_S_CTRL for +mute only. If the user would call VIDIOC_S_EXT_CTRLS for both mute and volume +controls, then the 'is_new' flag would be 1 for both controls. + +The 'is_new' flag is always 1 when called from v4l2_ctrl_handler_setup(). + + +Handling autogain/gain-type Controls with Auto Clusters +------------------------------------------------------- + +A common type of control cluster is one that handles 'auto-foo/foo'-type +controls. Typical examples are autogain/gain, autoexposure/exposure, +autowhitebalance/red balance/blue balance. In all cases you have one control +that determines whether another control is handled automatically by the hardware, +or whether it is under manual control from the user. + +If the cluster is in automatic mode, then the manual controls should be +marked inactive and volatile. When the volatile controls are read the +g_volatile_ctrl operation should return the value that the hardware's automatic +mode set up automatically. + +If the cluster is put in manual mode, then the manual controls should become +active again and the volatile flag is cleared (so g_volatile_ctrl is no longer +called while in manual mode). In addition just before switching to manual mode +the current values as determined by the auto mode are copied as the new manual +values. + +Finally the V4L2_CTRL_FLAG_UPDATE should be set for the auto control since +changing that control affects the control flags of the manual controls. + +In order to simplify this a special variation of v4l2_ctrl_cluster was +introduced: + +.. code-block:: c + + void v4l2_ctrl_auto_cluster(unsigned ncontrols, struct v4l2_ctrl **controls, + u8 manual_val, bool set_volatile); + +The first two arguments are identical to v4l2_ctrl_cluster. The third argument +tells the framework which value switches the cluster into manual mode. The +last argument will optionally set V4L2_CTRL_FLAG_VOLATILE for the non-auto controls. +If it is false, then the manual controls are never volatile. You would typically +use that if the hardware does not give you the option to read back to values as +determined by the auto mode (e.g. if autogain is on, the hardware doesn't allow +you to obtain the current gain value). + +The first control of the cluster is assumed to be the 'auto' control. + +Using this function will ensure that you don't need to handle all the complex +flag and volatile handling. + + +VIDIOC_LOG_STATUS Support +------------------------- + +This ioctl allow you to dump the current status of a driver to the kernel log. +The v4l2_ctrl_handler_log_status(ctrl_handler, prefix) can be used to dump the +value of the controls owned by the given handler to the log. You can supply a +prefix as well. If the prefix didn't end with a space, then ': ' will be added +for you. + + +Different Handlers for Different Video Nodes +-------------------------------------------- + +Usually the V4L2 driver has just one control handler that is global for +all video nodes. But you can also specify different control handlers for +different video nodes. You can do that by manually setting the ctrl_handler +field of struct video_device. + +That is no problem if there are no subdevs involved but if there are, then +you need to block the automatic merging of subdev controls to the global +control handler. You do that by simply setting the ctrl_handler field in +struct v4l2_device to NULL. Now v4l2_device_register_subdev() will no longer +merge subdev controls. + +After each subdev was added, you will then have to call v4l2_ctrl_add_handler +manually to add the subdev's control handler (sd->ctrl_handler) to the desired +control handler. This control handler may be specific to the video_device or +for a subset of video_device's. For example: the radio device nodes only have +audio controls, while the video and vbi device nodes share the same control +handler for the audio and video controls. + +If you want to have one handler (e.g. for a radio device node) have a subset +of another handler (e.g. for a video device node), then you should first add +the controls to the first handler, add the other controls to the second +handler and finally add the first handler to the second. For example: + +.. code-block:: c + + v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_VOLUME, ...); + v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...); + v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_BRIGHTNESS, ...); + v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_CONTRAST, ...); + v4l2_ctrl_add_handler(&video_ctrl_handler, &radio_ctrl_handler, NULL); + +The last argument to v4l2_ctrl_add_handler() is a filter function that allows +you to filter which controls will be added. Set it to NULL if you want to add +all controls. + +Or you can add specific controls to a handler: + +.. code-block:: c + + volume = v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_AUDIO_VOLUME, ...); + v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_BRIGHTNESS, ...); + v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_CONTRAST, ...); + +What you should not do is make two identical controls for two handlers. +For example: + +.. code-block:: c + + v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...); + v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_AUDIO_MUTE, ...); + +This would be bad since muting the radio would not change the video mute +control. The rule is to have one control for each hardware 'knob' that you +can twiddle. + + +Finding Controls +---------------- + +Normally you have created the controls yourself and you can store the struct +v4l2_ctrl pointer into your own struct. + +But sometimes you need to find a control from another handler that you do +not own. For example, if you have to find a volume control from a subdev. + +You can do that by calling v4l2_ctrl_find: + +.. code-block:: c + + struct v4l2_ctrl *volume; + + volume = v4l2_ctrl_find(sd->ctrl_handler, V4L2_CID_AUDIO_VOLUME); + +Since v4l2_ctrl_find will lock the handler you have to be careful where you +use it. For example, this is not a good idea: + +.. code-block:: c + + struct v4l2_ctrl_handler ctrl_handler; + + v4l2_ctrl_new_std(&ctrl_handler, &video_ops, V4L2_CID_BRIGHTNESS, ...); + v4l2_ctrl_new_std(&ctrl_handler, &video_ops, V4L2_CID_CONTRAST, ...); + +...and in video_ops.s_ctrl: + +.. code-block:: c + + case V4L2_CID_BRIGHTNESS: + contrast = v4l2_find_ctrl(&ctrl_handler, V4L2_CID_CONTRAST); + ... + +When s_ctrl is called by the framework the ctrl_handler.lock is already taken, so +attempting to find another control from the same handler will deadlock. + +It is recommended not to use this function from inside the control ops. + + +Preventing Controls inheritance +------------------------------- + +When one control handler is added to another using v4l2_ctrl_add_handler, then +by default all controls from one are merged to the other. But a subdev might +have low-level controls that make sense for some advanced embedded system, but +not when it is used in consumer-level hardware. In that case you want to keep +those low-level controls local to the subdev. You can do this by simply +setting the 'is_private' flag of the control to 1: + +.. code-block:: c + + static const struct v4l2_ctrl_config ctrl_private = { + .ops = &ctrl_custom_ops, + .id = V4L2_CID_..., + .name = "Some Private Control", + .type = V4L2_CTRL_TYPE_INTEGER, + .max = 15, + .step = 1, + .is_private = 1, + }; + + ctrl = v4l2_ctrl_new_custom(&foo->ctrl_handler, &ctrl_private, NULL); + +These controls will now be skipped when v4l2_ctrl_add_handler is called. + + +V4L2_CTRL_TYPE_CTRL_CLASS Controls +---------------------------------- + +Controls of this type can be used by GUIs to get the name of the control class. +A fully featured GUI can make a dialog with multiple tabs with each tab +containing the controls belonging to a particular control class. The name of +each tab can be found by querying a special control with ID <control class | 1>. + +Drivers do not have to care about this. The framework will automatically add +a control of this type whenever the first control belonging to a new control +class is added. + + +Adding Notify Callbacks +----------------------- + +Sometimes the platform or bridge driver needs to be notified when a control +from a sub-device driver changes. You can set a notify callback by calling +this function: + +.. code-block:: c + + void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl, + void (*notify)(struct v4l2_ctrl *ctrl, void *priv), void *priv); + +Whenever the give control changes value the notify callback will be called +with a pointer to the control and the priv pointer that was passed with +v4l2_ctrl_notify. Note that the control's handler lock is held when the +notify function is called. + +There can be only one notify function per control handler. Any attempt +to set another notify function will cause a WARN_ON. + +v4l2_ctrl functions and data structures +--------------------------------------- + +.. kernel-doc:: include/media/v4l2-ctrls.h diff --git a/Documentation/driver-api/media/v4l2-core.rst b/Documentation/driver-api/media/v4l2-core.rst new file mode 100644 index 000000000000..0dcad7a23141 --- /dev/null +++ b/Documentation/driver-api/media/v4l2-core.rst @@ -0,0 +1,29 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Video4Linux devices +------------------- + +.. toctree:: + :maxdepth: 1 + + v4l2-intro + v4l2-dev + v4l2-device + v4l2-fh + v4l2-subdev + v4l2-event + v4l2-controls + v4l2-videobuf + v4l2-videobuf2 + v4l2-clocks + v4l2-dv-timings + v4l2-flash-led-class + v4l2-mc + v4l2-mediabus + v4l2-mem2mem + v4l2-async + v4l2-fwnode + v4l2-rect + v4l2-tuner + v4l2-common + v4l2-tveeprom diff --git a/Documentation/driver-api/media/v4l2-dev.rst b/Documentation/driver-api/media/v4l2-dev.rst new file mode 100644 index 000000000000..63c064837c00 --- /dev/null +++ b/Documentation/driver-api/media/v4l2-dev.rst @@ -0,0 +1,375 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Video device' s internal representation +======================================= + +The actual device nodes in the ``/dev`` directory are created using the +:c:type:`video_device` struct (``v4l2-dev.h``). This struct can either be +allocated dynamically or embedded in a larger struct. + +To allocate it dynamically use :c:func:`video_device_alloc`: + +.. code-block:: c + + struct video_device *vdev = video_device_alloc(); + + if (vdev == NULL) + return -ENOMEM; + + vdev->release = video_device_release; + +If you embed it in a larger struct, then you must set the ``release()`` +callback to your own function: + +.. code-block:: c + + struct video_device *vdev = &my_vdev->vdev; + + vdev->release = my_vdev_release; + +The ``release()`` callback must be set and it is called when the last user +of the video device exits. + +The default :c:func:`video_device_release` callback currently +just calls ``kfree`` to free the allocated memory. + +There is also a :c:func:`video_device_release_empty` function that does +nothing (is empty) and should be used if the struct is embedded and there +is nothing to do when it is released. + +You should also set these fields of :c:type:`video_device`: + +- :c:type:`video_device`->v4l2_dev: must be set to the :c:type:`v4l2_device` + parent device. + +- :c:type:`video_device`->name: set to something descriptive and unique. + +- :c:type:`video_device`->vfl_dir: set this to ``VFL_DIR_RX`` for capture + devices (``VFL_DIR_RX`` has value 0, so this is normally already the + default), set to ``VFL_DIR_TX`` for output devices and ``VFL_DIR_M2M`` for mem2mem (codec) devices. + +- :c:type:`video_device`->fops: set to the :c:type:`v4l2_file_operations` + struct. + +- :c:type:`video_device`->ioctl_ops: if you use the :c:type:`v4l2_ioctl_ops` + to simplify ioctl maintenance (highly recommended to use this and it might + become compulsory in the future!), then set this to your + :c:type:`v4l2_ioctl_ops` struct. The :c:type:`video_device`->vfl_type and + :c:type:`video_device`->vfl_dir fields are used to disable ops that do not + match the type/dir combination. E.g. VBI ops are disabled for non-VBI nodes, + and output ops are disabled for a capture device. This makes it possible to + provide just one :c:type:`v4l2_ioctl_ops` struct for both vbi and + video nodes. + +- :c:type:`video_device`->lock: leave to ``NULL`` if you want to do all the + locking in the driver. Otherwise you give it a pointer to a struct + ``mutex_lock`` and before the :c:type:`video_device`->unlocked_ioctl + file operation is called this lock will be taken by the core and released + afterwards. See the next section for more details. + +- :c:type:`video_device`->queue: a pointer to the struct :c:type:`vb2_queue` + associated with this device node. + If queue is not ``NULL``, and queue->lock is not ``NULL``, then queue->lock + is used for the queuing ioctls (``VIDIOC_REQBUFS``, ``CREATE_BUFS``, + ``QBUF``, ``DQBUF``, ``QUERYBUF``, ``PREPARE_BUF``, ``STREAMON`` and + ``STREAMOFF``) instead of the lock above. + That way the :ref:`vb2 <vb2_framework>` queuing framework does not have + to wait for other ioctls. This queue pointer is also used by the + :ref:`vb2 <vb2_framework>` helper functions to check for + queuing ownership (i.e. is the filehandle calling it allowed to do the + operation). + +- :c:type:`video_device`->prio: keeps track of the priorities. Used to + implement ``VIDIOC_G_PRIORITY`` and ``VIDIOC_S_PRIORITY``. + If left to ``NULL``, then it will use the struct :c:type:`v4l2_prio_state` + in :c:type:`v4l2_device`. If you want to have a separate priority state per + (group of) device node(s), then you can point it to your own struct + :c:type:`v4l2_prio_state`. + +- :c:type:`video_device`->dev_parent: you only set this if v4l2_device was + registered with ``NULL`` as the parent ``device`` struct. This only happens + in cases where one hardware device has multiple PCI devices that all share + the same :c:type:`v4l2_device` core. + + The cx88 driver is an example of this: one core :c:type:`v4l2_device` struct, + but it is used by both a raw video PCI device (cx8800) and a MPEG PCI device + (cx8802). Since the :c:type:`v4l2_device` cannot be associated with two PCI + devices at the same time it is setup without a parent device. But when the + struct :c:type:`video_device` is initialized you **do** know which parent + PCI device to use and so you set ``dev_device`` to the correct PCI device. + +If you use :c:type:`v4l2_ioctl_ops`, then you should set +:c:type:`video_device`->unlocked_ioctl to :c:func:`video_ioctl2` in your +:c:type:`v4l2_file_operations` struct. + +In some cases you want to tell the core that a function you had specified in +your :c:type:`v4l2_ioctl_ops` should be ignored. You can mark such ioctls by +calling this function before :c:func:`video_register_device` is called: + + :c:func:`v4l2_disable_ioctl <v4l2_disable_ioctl>` + (:c:type:`vdev <video_device>`, cmd). + +This tends to be needed if based on external factors (e.g. which card is +being used) you want to turns off certain features in :c:type:`v4l2_ioctl_ops` +without having to make a new struct. + +The :c:type:`v4l2_file_operations` struct is a subset of file_operations. +The main difference is that the inode argument is omitted since it is never +used. + +If integration with the media framework is needed, you must initialize the +:c:type:`media_entity` struct embedded in the :c:type:`video_device` struct +(entity field) by calling :c:func:`media_entity_pads_init`: + +.. code-block:: c + + struct media_pad *pad = &my_vdev->pad; + int err; + + err = media_entity_pads_init(&vdev->entity, 1, pad); + +The pads array must have been previously initialized. There is no need to +manually set the struct media_entity type and name fields. + +A reference to the entity will be automatically acquired/released when the +video device is opened/closed. + +ioctls and locking +------------------ + +The V4L core provides optional locking services. The main service is the +lock field in struct :c:type:`video_device`, which is a pointer to a mutex. +If you set this pointer, then that will be used by unlocked_ioctl to +serialize all ioctls. + +If you are using the :ref:`videobuf2 framework <vb2_framework>`, then there +is a second lock that you can set: :c:type:`video_device`->queue->lock. If +set, then this lock will be used instead of :c:type:`video_device`->lock +to serialize all queuing ioctls (see the previous section +for the full list of those ioctls). + +The advantage of using a different lock for the queuing ioctls is that for some +drivers (particularly USB drivers) certain commands such as setting controls +can take a long time, so you want to use a separate lock for the buffer queuing +ioctls. That way your ``VIDIOC_DQBUF`` doesn't stall because the driver is busy +changing the e.g. exposure of the webcam. + +Of course, you can always do all the locking yourself by leaving both lock +pointers at ``NULL``. + +If you use the old :ref:`videobuf framework <vb_framework>` then you must +pass the :c:type:`video_device`->lock to the videobuf queue initialize +function: if videobuf has to wait for a frame to arrive, then it will +temporarily unlock the lock and relock it afterwards. If your driver also +waits in the code, then you should do the same to allow other +processes to access the device node while the first process is waiting for +something. + +In the case of :ref:`videobuf2 <vb2_framework>` you will need to implement the +``wait_prepare()`` and ``wait_finish()`` callbacks to unlock/lock if applicable. +If you use the ``queue->lock`` pointer, then you can use the helper functions +:c:func:`vb2_ops_wait_prepare` and :c:func:`vb2_ops_wait_finish`. + +The implementation of a hotplug disconnect should also take the lock from +:c:type:`video_device` before calling v4l2_device_disconnect. If you are also +using :c:type:`video_device`->queue->lock, then you have to first lock +:c:type:`video_device`->queue->lock followed by :c:type:`video_device`->lock. +That way you can be sure no ioctl is running when you call +:c:func:`v4l2_device_disconnect`. + +Video device registration +------------------------- + +Next you register the video device with :c:func:`video_register_device`. +This will create the character device for you. + +.. code-block:: c + + err = video_register_device(vdev, VFL_TYPE_VIDEO, -1); + if (err) { + video_device_release(vdev); /* or kfree(my_vdev); */ + return err; + } + +If the :c:type:`v4l2_device` parent device has a not ``NULL`` mdev field, +the video device entity will be automatically registered with the media +device. + +Which device is registered depends on the type argument. The following +types exist: + +========================== ==================== ============================== +:c:type:`vfl_devnode_type` Device name Usage +========================== ==================== ============================== +``VFL_TYPE_VIDEO`` ``/dev/videoX`` for video input/output devices +``VFL_TYPE_VBI`` ``/dev/vbiX`` for vertical blank data (i.e. + closed captions, teletext) +``VFL_TYPE_RADIO`` ``/dev/radioX`` for radio tuners +``VFL_TYPE_SUBDEV`` ``/dev/v4l-subdevX`` for V4L2 subdevices +``VFL_TYPE_SDR`` ``/dev/swradioX`` for Software Defined Radio + (SDR) tuners +``VFL_TYPE_TOUCH`` ``/dev/v4l-touchX`` for touch sensors +========================== ==================== ============================== + +The last argument gives you a certain amount of control over the device +device node number used (i.e. the X in ``videoX``). Normally you will pass -1 +to let the v4l2 framework pick the first free number. But sometimes users +want to select a specific node number. It is common that drivers allow +the user to select a specific device node number through a driver module +option. That number is then passed to this function and video_register_device +will attempt to select that device node number. If that number was already +in use, then the next free device node number will be selected and it +will send a warning to the kernel log. + +Another use-case is if a driver creates many devices. In that case it can +be useful to place different video devices in separate ranges. For example, +video capture devices start at 0, video output devices start at 16. +So you can use the last argument to specify a minimum device node number +and the v4l2 framework will try to pick the first free number that is equal +or higher to what you passed. If that fails, then it will just pick the +first free number. + +Since in this case you do not care about a warning about not being able +to select the specified device node number, you can call the function +:c:func:`video_register_device_no_warn` instead. + +Whenever a device node is created some attributes are also created for you. +If you look in ``/sys/class/video4linux`` you see the devices. Go into e.g. +``video0`` and you will see 'name', 'dev_debug' and 'index' attributes. The +'name' attribute is the 'name' field of the video_device struct. The +'dev_debug' attribute can be used to enable core debugging. See the next +section for more detailed information on this. + +The 'index' attribute is the index of the device node: for each call to +:c:func:`video_register_device()` the index is just increased by 1. The +first video device node you register always starts with index 0. + +Users can setup udev rules that utilize the index attribute to make fancy +device names (e.g. '``mpegX``' for MPEG video capture device nodes). + +After the device was successfully registered, then you can use these fields: + +- :c:type:`video_device`->vfl_type: the device type passed to + :c:func:`video_register_device`. +- :c:type:`video_device`->minor: the assigned device minor number. +- :c:type:`video_device`->num: the device node number (i.e. the X in + ``videoX``). +- :c:type:`video_device`->index: the device index number. + +If the registration failed, then you need to call +:c:func:`video_device_release` to free the allocated :c:type:`video_device` +struct, or free your own struct if the :c:type:`video_device` was embedded in +it. The ``vdev->release()`` callback will never be called if the registration +failed, nor should you ever attempt to unregister the device if the +registration failed. + +video device debugging +---------------------- + +The 'dev_debug' attribute that is created for each video, vbi, radio or swradio +device in ``/sys/class/video4linux/<devX>/`` allows you to enable logging of +file operations. + +It is a bitmask and the following bits can be set: + +.. tabularcolumns:: |p{5ex}|L| + +===== ================================================================ +Mask Description +===== ================================================================ +0x01 Log the ioctl name and error code. VIDIOC_(D)QBUF ioctls are + only logged if bit 0x08 is also set. +0x02 Log the ioctl name arguments and error code. VIDIOC_(D)QBUF + ioctls are + only logged if bit 0x08 is also set. +0x04 Log the file operations open, release, read, write, mmap and + get_unmapped_area. The read and write operations are only + logged if bit 0x08 is also set. +0x08 Log the read and write file operations and the VIDIOC_QBUF and + VIDIOC_DQBUF ioctls. +0x10 Log the poll file operation. +0x20 Log error and messages in the control operations. +===== ================================================================ + +Video device cleanup +-------------------- + +When the video device nodes have to be removed, either during the unload +of the driver or because the USB device was disconnected, then you should +unregister them with: + + :c:func:`video_unregister_device` + (:c:type:`vdev <video_device>`); + +This will remove the device nodes from sysfs (causing udev to remove them +from ``/dev``). + +After :c:func:`video_unregister_device` returns no new opens can be done. +However, in the case of USB devices some application might still have one of +these device nodes open. So after the unregister all file operations (except +release, of course) will return an error as well. + +When the last user of the video device node exits, then the ``vdev->release()`` +callback is called and you can do the final cleanup there. + +Don't forget to cleanup the media entity associated with the video device if +it has been initialized: + + :c:func:`media_entity_cleanup <media_entity_cleanup>` + (&vdev->entity); + +This can be done from the release callback. + + +helper functions +---------------- + +There are a few useful helper functions: + +- file and :c:type:`video_device` private data + +You can set/get driver private data in the video_device struct using: + + :c:func:`video_get_drvdata <video_get_drvdata>` + (:c:type:`vdev <video_device>`); + + :c:func:`video_set_drvdata <video_set_drvdata>` + (:c:type:`vdev <video_device>`); + +Note that you can safely call :c:func:`video_set_drvdata` before calling +:c:func:`video_register_device`. + +And this function: + + :c:func:`video_devdata <video_devdata>` + (struct file \*file); + +returns the video_device belonging to the file struct. + +The :c:func:`video_devdata` function combines :c:func:`video_get_drvdata` +with :c:func:`video_devdata`: + + :c:func:`video_drvdata <video_drvdata>` + (struct file \*file); + +You can go from a :c:type:`video_device` struct to the v4l2_device struct using: + +.. code-block:: c + + struct v4l2_device *v4l2_dev = vdev->v4l2_dev; + +- Device node name + +The :c:type:`video_device` node kernel name can be retrieved using: + + :c:func:`video_device_node_name <video_device_node_name>` + (:c:type:`vdev <video_device>`); + +The name is used as a hint by userspace tools such as udev. The function +should be used where possible instead of accessing the video_device::num and +video_device::minor fields. + +video_device functions and data structures +------------------------------------------ + +.. kernel-doc:: include/media/v4l2-dev.h diff --git a/Documentation/driver-api/media/v4l2-device.rst b/Documentation/driver-api/media/v4l2-device.rst new file mode 100644 index 000000000000..5e25bf182c18 --- /dev/null +++ b/Documentation/driver-api/media/v4l2-device.rst @@ -0,0 +1,146 @@ +.. SPDX-License-Identifier: GPL-2.0 + +V4L2 device instance +-------------------- + +Each device instance is represented by a struct :c:type:`v4l2_device`. +Very simple devices can just allocate this struct, but most of the time you +would embed this struct inside a larger struct. + +You must register the device instance by calling: + + :c:func:`v4l2_device_register <v4l2_device_register>` + (dev, :c:type:`v4l2_dev <v4l2_device>`). + +Registration will initialize the :c:type:`v4l2_device` struct. If the +dev->driver_data field is ``NULL``, it will be linked to +:c:type:`v4l2_dev <v4l2_device>` argument. + +Drivers that want integration with the media device framework need to set +dev->driver_data manually to point to the driver-specific device structure +that embed the struct :c:type:`v4l2_device` instance. This is achieved by a +``dev_set_drvdata()`` call before registering the V4L2 device instance. +They must also set the struct :c:type:`v4l2_device` mdev field to point to a +properly initialized and registered :c:type:`media_device` instance. + +If :c:type:`v4l2_dev <v4l2_device>`\ ->name is empty then it will be set to a +value derived from dev (driver name followed by the bus_id, to be precise). +If you set it up before calling :c:func:`v4l2_device_register` then it will +be untouched. If dev is ``NULL``, then you **must** setup +:c:type:`v4l2_dev <v4l2_device>`\ ->name before calling +:c:func:`v4l2_device_register`. + +You can use :c:func:`v4l2_device_set_name` to set the name based on a driver +name and a driver-global atomic_t instance. This will generate names like +``ivtv0``, ``ivtv1``, etc. If the name ends with a digit, then it will insert +a dash: ``cx18-0``, ``cx18-1``, etc. This function returns the instance number. + +The first ``dev`` argument is normally the ``struct device`` pointer of a +``pci_dev``, ``usb_interface`` or ``platform_device``. It is rare for dev to +be ``NULL``, but it happens with ISA devices or when one device creates +multiple PCI devices, thus making it impossible to associate +:c:type:`v4l2_dev <v4l2_device>` with a particular parent. + +You can also supply a ``notify()`` callback that can be called by sub-devices +to notify you of events. Whether you need to set this depends on the +sub-device. Any notifications a sub-device supports must be defined in a header +in ``include/media/subdevice.h``. + +V4L2 devices are unregistered by calling: + + :c:func:`v4l2_device_unregister` + (:c:type:`v4l2_dev <v4l2_device>`). + +If the dev->driver_data field points to :c:type:`v4l2_dev <v4l2_device>`, +it will be reset to ``NULL``. Unregistering will also automatically unregister +all subdevs from the device. + +If you have a hotpluggable device (e.g. a USB device), then when a disconnect +happens the parent device becomes invalid. Since :c:type:`v4l2_device` has a +pointer to that parent device it has to be cleared as well to mark that the +parent is gone. To do this call: + + :c:func:`v4l2_device_disconnect` + (:c:type:`v4l2_dev <v4l2_device>`). + +This does *not* unregister the subdevs, so you still need to call the +:c:func:`v4l2_device_unregister` function for that. If your driver is not +hotpluggable, then there is no need to call :c:func:`v4l2_device_disconnect`. + +Sometimes you need to iterate over all devices registered by a specific +driver. This is usually the case if multiple device drivers use the same +hardware. E.g. the ivtvfb driver is a framebuffer driver that uses the ivtv +hardware. The same is true for alsa drivers for example. + +You can iterate over all registered devices as follows: + +.. code-block:: c + + static int callback(struct device *dev, void *p) + { + struct v4l2_device *v4l2_dev = dev_get_drvdata(dev); + + /* test if this device was inited */ + if (v4l2_dev == NULL) + return 0; + ... + return 0; + } + + int iterate(void *p) + { + struct device_driver *drv; + int err; + + /* Find driver 'ivtv' on the PCI bus. + pci_bus_type is a global. For USB buses use usb_bus_type. */ + drv = driver_find("ivtv", &pci_bus_type); + /* iterate over all ivtv device instances */ + err = driver_for_each_device(drv, NULL, p, callback); + put_driver(drv); + return err; + } + +Sometimes you need to keep a running counter of the device instance. This is +commonly used to map a device instance to an index of a module option array. + +The recommended approach is as follows: + +.. code-block:: c + + static atomic_t drv_instance = ATOMIC_INIT(0); + + static int drv_probe(struct pci_dev *pdev, const struct pci_device_id *pci_id) + { + ... + state->instance = atomic_inc_return(&drv_instance) - 1; + } + +If you have multiple device nodes then it can be difficult to know when it is +safe to unregister :c:type:`v4l2_device` for hotpluggable devices. For this +purpose :c:type:`v4l2_device` has refcounting support. The refcount is +increased whenever :c:func:`video_register_device` is called and it is +decreased whenever that device node is released. When the refcount reaches +zero, then the :c:type:`v4l2_device` release() callback is called. You can +do your final cleanup there. + +If other device nodes (e.g. ALSA) are created, then you can increase and +decrease the refcount manually as well by calling: + + :c:func:`v4l2_device_get` + (:c:type:`v4l2_dev <v4l2_device>`). + +or: + + :c:func:`v4l2_device_put` + (:c:type:`v4l2_dev <v4l2_device>`). + +Since the initial refcount is 1 you also need to call +:c:func:`v4l2_device_put` in the ``disconnect()`` callback (for USB devices) +or in the ``remove()`` callback (for e.g. PCI devices), otherwise the refcount +will never reach 0. + +v4l2_device functions and data structures +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. kernel-doc:: include/media/v4l2-device.h diff --git a/Documentation/driver-api/media/v4l2-dv-timings.rst b/Documentation/driver-api/media/v4l2-dv-timings.rst new file mode 100644 index 000000000000..b178f931518b --- /dev/null +++ b/Documentation/driver-api/media/v4l2-dv-timings.rst @@ -0,0 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 + +V4L2 DV Timings functions +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. kernel-doc:: include/media/v4l2-dv-timings.h diff --git a/Documentation/driver-api/media/v4l2-event.rst b/Documentation/driver-api/media/v4l2-event.rst new file mode 100644 index 000000000000..a4b7ae2b94d8 --- /dev/null +++ b/Documentation/driver-api/media/v4l2-event.rst @@ -0,0 +1,181 @@ +.. SPDX-License-Identifier: GPL-2.0 + +V4L2 events +----------- + +The V4L2 events provide a generic way to pass events to user space. +The driver must use :c:type:`v4l2_fh` to be able to support V4L2 events. + +Events are subscribed per-filehandle. An event specification consists of a +``type`` and is optionally associated with an object identified through the +``id`` field. If unused, then the ``id`` is 0. So an event is uniquely +identified by the ``(type, id)`` tuple. + +The :c:type:`v4l2_fh` struct has a list of subscribed events on its +``subscribed`` field. + +When the user subscribes to an event, a :c:type:`v4l2_subscribed_event` +struct is added to :c:type:`v4l2_fh`\ ``.subscribed``, one for every +subscribed event. + +Each :c:type:`v4l2_subscribed_event` struct ends with a +:c:type:`v4l2_kevent` ringbuffer, with the size given by the caller +of :c:func:`v4l2_event_subscribe`. This ringbuffer is used to store any events +raised by the driver. + +So every ``(type, ID)`` event tuple will have its own +:c:type:`v4l2_kevent` ringbuffer. This guarantees that if a driver is +generating lots of events of one type in a short time, then that will +not overwrite events of another type. + +But if you get more events of one type than the size of the +:c:type:`v4l2_kevent` ringbuffer, then the oldest event will be dropped +and the new one added. + +The :c:type:`v4l2_kevent` struct links into the ``available`` +list of the :c:type:`v4l2_fh` struct so :ref:`VIDIOC_DQEVENT` will +know which event to dequeue first. + +Finally, if the event subscription is associated with a particular object +such as a V4L2 control, then that object needs to know about that as well +so that an event can be raised by that object. So the ``node`` field can +be used to link the :c:type:`v4l2_subscribed_event` struct into a list of +such objects. + +So to summarize: + +- struct :c:type:`v4l2_fh` has two lists: one of the ``subscribed`` events, + and one of the ``available`` events. + +- struct :c:type:`v4l2_subscribed_event` has a ringbuffer of raised + (pending) events of that particular type. + +- If struct :c:type:`v4l2_subscribed_event` is associated with a specific + object, then that object will have an internal list of + struct :c:type:`v4l2_subscribed_event` so it knows who subscribed an + event to that object. + +Furthermore, the internal struct :c:type:`v4l2_subscribed_event` has +``merge()`` and ``replace()`` callbacks which drivers can set. These +callbacks are called when a new event is raised and there is no more room. + +The ``replace()`` callback allows you to replace the payload of the old event +with that of the new event, merging any relevant data from the old payload +into the new payload that replaces it. It is called when this event type has +a ringbuffer with size is one, i.e. only one event can be stored in the +ringbuffer. + +The ``merge()`` callback allows you to merge the oldest event payload into +that of the second-oldest event payload. It is called when +the ringbuffer has size is greater than one. + +This way no status information is lost, just the intermediate steps leading +up to that state. + +A good example of these ``replace``/``merge`` callbacks is in v4l2-event.c: +``ctrls_replace()`` and ``ctrls_merge()`` callbacks for the control event. + +.. note:: + these callbacks can be called from interrupt context, so they must + be fast. + +In order to queue events to video device, drivers should call: + + :c:func:`v4l2_event_queue <v4l2_event_queue>` + (:c:type:`vdev <video_device>`, :c:type:`ev <v4l2_event>`) + +The driver's only responsibility is to fill in the type and the data fields. +The other fields will be filled in by V4L2. + +Event subscription +~~~~~~~~~~~~~~~~~~ + +Subscribing to an event is via: + + :c:func:`v4l2_event_subscribe <v4l2_event_subscribe>` + (:c:type:`fh <v4l2_fh>`, :c:type:`sub <v4l2_event_subscription>` , + elems, :c:type:`ops <v4l2_subscribed_event_ops>`) + + +This function is used to implement :c:type:`video_device`-> +:c:type:`ioctl_ops <v4l2_ioctl_ops>`-> ``vidioc_subscribe_event``, +but the driver must check first if the driver is able to produce events +with specified event id, and then should call +:c:func:`v4l2_event_subscribe` to subscribe the event. + +The elems argument is the size of the event queue for this event. If it is 0, +then the framework will fill in a default value (this depends on the event +type). + +The ops argument allows the driver to specify a number of callbacks: + +.. tabularcolumns:: |p{1.5cm}|p{16.0cm}| + +======== ============================================================== +Callback Description +======== ============================================================== +add called when a new listener gets added (subscribing to the same + event twice will only cause this callback to get called once) +del called when a listener stops listening +replace replace event 'old' with event 'new'. +merge merge event 'old' into event 'new'. +======== ============================================================== + +All 4 callbacks are optional, if you don't want to specify any callbacks +the ops argument itself maybe ``NULL``. + +Unsubscribing an event +~~~~~~~~~~~~~~~~~~~~~~ + +Unsubscribing to an event is via: + + :c:func:`v4l2_event_unsubscribe <v4l2_event_unsubscribe>` + (:c:type:`fh <v4l2_fh>`, :c:type:`sub <v4l2_event_subscription>`) + +This function is used to implement :c:type:`video_device`-> +:c:type:`ioctl_ops <v4l2_ioctl_ops>`-> ``vidioc_unsubscribe_event``. +A driver may call :c:func:`v4l2_event_unsubscribe` directly unless it +wants to be involved in unsubscription process. + +The special type ``V4L2_EVENT_ALL`` may be used to unsubscribe all events. The +drivers may want to handle this in a special way. + +Check if there's a pending event +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Checking if there's a pending event is via: + + :c:func:`v4l2_event_pending <v4l2_event_pending>` + (:c:type:`fh <v4l2_fh>`) + + +This function returns the number of pending events. Useful when implementing +poll. + +How events work +~~~~~~~~~~~~~~~ + +Events are delivered to user space through the poll system call. The driver +can use :c:type:`v4l2_fh`->wait (a wait_queue_head_t) as the argument for +``poll_wait()``. + +There are standard and private events. New standard events must use the +smallest available event type. The drivers must allocate their events from +their own class starting from class base. Class base is +``V4L2_EVENT_PRIVATE_START`` + n * 1000 where n is the lowest available number. +The first event type in the class is reserved for future use, so the first +available event type is 'class base + 1'. + +An example on how the V4L2 events may be used can be found in the OMAP +3 ISP driver (``drivers/media/platform/omap3isp``). + +A subdev can directly send an event to the :c:type:`v4l2_device` notify +function with ``V4L2_DEVICE_NOTIFY_EVENT``. This allows the bridge to map +the subdev that sends the event to the video node(s) associated with the +subdev that need to be informed about such an event. + +V4L2 event functions and data structures +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. kernel-doc:: include/media/v4l2-event.h + diff --git a/Documentation/driver-api/media/v4l2-fh.rst b/Documentation/driver-api/media/v4l2-fh.rst new file mode 100644 index 000000000000..4c62b19af744 --- /dev/null +++ b/Documentation/driver-api/media/v4l2-fh.rst @@ -0,0 +1,141 @@ +.. SPDX-License-Identifier: GPL-2.0 + +V4L2 File handlers +------------------ + +struct :c:type:`v4l2_fh` provides a way to easily keep file handle specific +data that is used by the V4L2 framework. + +.. attention:: + New drivers must use struct :c:type:`v4l2_fh` + since it is also used to implement priority handling + (:ref:`VIDIOC_G_PRIORITY`). + +The users of :c:type:`v4l2_fh` (in the V4L2 framework, not the driver) know +whether a driver uses :c:type:`v4l2_fh` as its ``file->private_data`` pointer +by testing the ``V4L2_FL_USES_V4L2_FH`` bit in :c:type:`video_device`->flags. +This bit is set whenever :c:func:`v4l2_fh_init` is called. + +struct :c:type:`v4l2_fh` is allocated as a part of the driver's own file handle +structure and ``file->private_data`` is set to it in the driver's ``open()`` +function by the driver. + +In many cases the struct :c:type:`v4l2_fh` will be embedded in a larger +structure. In that case you should call: + +#) :c:func:`v4l2_fh_init` and :c:func:`v4l2_fh_add` in ``open()`` +#) :c:func:`v4l2_fh_del` and :c:func:`v4l2_fh_exit` in ``release()`` + +Drivers can extract their own file handle structure by using the container_of +macro. + +Example: + +.. code-block:: c + + struct my_fh { + int blah; + struct v4l2_fh fh; + }; + + ... + + int my_open(struct file *file) + { + struct my_fh *my_fh; + struct video_device *vfd; + int ret; + + ... + + my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL); + + ... + + v4l2_fh_init(&my_fh->fh, vfd); + + ... + + file->private_data = &my_fh->fh; + v4l2_fh_add(&my_fh->fh); + return 0; + } + + int my_release(struct file *file) + { + struct v4l2_fh *fh = file->private_data; + struct my_fh *my_fh = container_of(fh, struct my_fh, fh); + + ... + v4l2_fh_del(&my_fh->fh); + v4l2_fh_exit(&my_fh->fh); + kfree(my_fh); + return 0; + } + +Below is a short description of the :c:type:`v4l2_fh` functions used: + +:c:func:`v4l2_fh_init <v4l2_fh_init>` +(:c:type:`fh <v4l2_fh>`, :c:type:`vdev <video_device>`) + + +- Initialise the file handle. This **MUST** be performed in the driver's + :c:type:`v4l2_file_operations`->open() handler. + + +:c:func:`v4l2_fh_add <v4l2_fh_add>` +(:c:type:`fh <v4l2_fh>`) + +- Add a :c:type:`v4l2_fh` to :c:type:`video_device` file handle list. + Must be called once the file handle is completely initialized. + +:c:func:`v4l2_fh_del <v4l2_fh_del>` +(:c:type:`fh <v4l2_fh>`) + +- Unassociate the file handle from :c:type:`video_device`. The file handle + exit function may now be called. + +:c:func:`v4l2_fh_exit <v4l2_fh_exit>` +(:c:type:`fh <v4l2_fh>`) + +- Uninitialise the file handle. After uninitialisation the :c:type:`v4l2_fh` + memory can be freed. + + +If struct :c:type:`v4l2_fh` is not embedded, then you can use these helper functions: + +:c:func:`v4l2_fh_open <v4l2_fh_open>` +(struct file \*filp) + +- This allocates a struct :c:type:`v4l2_fh`, initializes it and adds it to + the struct :c:type:`video_device` associated with the file struct. + +:c:func:`v4l2_fh_release <v4l2_fh_release>` +(struct file \*filp) + +- This deletes it from the struct :c:type:`video_device` associated with the + file struct, uninitialised the :c:type:`v4l2_fh` and frees it. + +These two functions can be plugged into the v4l2_file_operation's ``open()`` +and ``release()`` ops. + +Several drivers need to do something when the first file handle is opened and +when the last file handle closes. Two helper functions were added to check +whether the :c:type:`v4l2_fh` struct is the only open filehandle of the +associated device node: + +:c:func:`v4l2_fh_is_singular <v4l2_fh_is_singular>` +(:c:type:`fh <v4l2_fh>`) + +- Returns 1 if the file handle is the only open file handle, else 0. + +:c:func:`v4l2_fh_is_singular_file <v4l2_fh_is_singular_file>` +(struct file \*filp) + +- Same, but it calls v4l2_fh_is_singular with filp->private_data. + + +V4L2 fh functions and data structures +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. kernel-doc:: include/media/v4l2-fh.h diff --git a/Documentation/driver-api/media/v4l2-flash-led-class.rst b/Documentation/driver-api/media/v4l2-flash-led-class.rst new file mode 100644 index 000000000000..2aa6bed9b8db --- /dev/null +++ b/Documentation/driver-api/media/v4l2-flash-led-class.rst @@ -0,0 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 + +V4L2 flash functions and data structures +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. kernel-doc:: include/media/v4l2-flash-led-class.h diff --git a/Documentation/driver-api/media/v4l2-fwnode.rst b/Documentation/driver-api/media/v4l2-fwnode.rst new file mode 100644 index 000000000000..e313b6cddcd0 --- /dev/null +++ b/Documentation/driver-api/media/v4l2-fwnode.rst @@ -0,0 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + +V4L2 fwnode kAPI +^^^^^^^^^^^^^^^^ +.. kernel-doc:: include/media/v4l2-fwnode.h diff --git a/Documentation/driver-api/media/v4l2-intro.rst b/Documentation/driver-api/media/v4l2-intro.rst new file mode 100644 index 000000000000..4d54fa9d7a12 --- /dev/null +++ b/Documentation/driver-api/media/v4l2-intro.rst @@ -0,0 +1,76 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Introduction +------------ + +The V4L2 drivers tend to be very complex due to the complexity of the +hardware: most devices have multiple ICs, export multiple device nodes in +/dev, and create also non-V4L2 devices such as DVB, ALSA, FB, I2C and input +(IR) devices. + +Especially the fact that V4L2 drivers have to setup supporting ICs to +do audio/video muxing/encoding/decoding makes it more complex than most. +Usually these ICs are connected to the main bridge driver through one or +more I2C buses, but other buses can also be used. Such devices are +called 'sub-devices'. + +For a long time the framework was limited to the video_device struct for +creating V4L device nodes and video_buf for handling the video buffers +(note that this document does not discuss the video_buf framework). + +This meant that all drivers had to do the setup of device instances and +connecting to sub-devices themselves. Some of this is quite complicated +to do right and many drivers never did do it correctly. + +There is also a lot of common code that could never be refactored due to +the lack of a framework. + +So this framework sets up the basic building blocks that all drivers +need and this same framework should make it much easier to refactor +common code into utility functions shared by all drivers. + +A good example to look at as a reference is the v4l2-pci-skeleton.c +source that is available in samples/v4l/. It is a skeleton driver for +a PCI capture card, and demonstrates how to use the V4L2 driver +framework. It can be used as a template for real PCI video capture driver. + +Structure of a V4L driver +------------------------- + +All drivers have the following structure: + +1) A struct for each device instance containing the device state. + +2) A way of initializing and commanding sub-devices (if any). + +3) Creating V4L2 device nodes (/dev/videoX, /dev/vbiX and /dev/radioX) + and keeping track of device-node specific data. + +4) Filehandle-specific structs containing per-filehandle data; + +5) video buffer handling. + +This is a rough schematic of how it all relates: + +.. code-block:: none + + device instances + | + +-sub-device instances + | + \-V4L2 device nodes + | + \-filehandle instances + + +Structure of the V4L2 framework +------------------------------- + +The framework closely resembles the driver structure: it has a v4l2_device +struct for the device instance data, a v4l2_subdev struct to refer to +sub-device instances, the video_device struct stores V4L2 device node data +and the v4l2_fh struct keeps track of filehandle instances. + +The V4L2 framework also optionally integrates with the media framework. If a +driver sets the struct v4l2_device mdev field, sub-devices and video nodes +will automatically appear in the media framework as entities. diff --git a/Documentation/driver-api/media/v4l2-mc.rst b/Documentation/driver-api/media/v4l2-mc.rst new file mode 100644 index 000000000000..0c352ac588b2 --- /dev/null +++ b/Documentation/driver-api/media/v4l2-mc.rst @@ -0,0 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 + +V4L2 Media Controller functions and data structures +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. kernel-doc:: include/media/v4l2-mc.h diff --git a/Documentation/driver-api/media/v4l2-mediabus.rst b/Documentation/driver-api/media/v4l2-mediabus.rst new file mode 100644 index 000000000000..1f2254cba92d --- /dev/null +++ b/Documentation/driver-api/media/v4l2-mediabus.rst @@ -0,0 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 + +V4L2 Media Bus functions and data structures +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. kernel-doc:: include/media/v4l2-mediabus.h diff --git a/Documentation/driver-api/media/v4l2-mem2mem.rst b/Documentation/driver-api/media/v4l2-mem2mem.rst new file mode 100644 index 000000000000..a43b31cc8261 --- /dev/null +++ b/Documentation/driver-api/media/v4l2-mem2mem.rst @@ -0,0 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 + +V4L2 Memory to Memory functions and data structures +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. kernel-doc:: include/media/v4l2-mem2mem.h diff --git a/Documentation/driver-api/media/v4l2-rect.rst b/Documentation/driver-api/media/v4l2-rect.rst new file mode 100644 index 000000000000..fc315cd84156 --- /dev/null +++ b/Documentation/driver-api/media/v4l2-rect.rst @@ -0,0 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 + +V4L2 rect helper functions +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. kernel-doc:: include/media/v4l2-rect.h diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst new file mode 100644 index 000000000000..6ced2381952a --- /dev/null +++ b/Documentation/driver-api/media/v4l2-subdev.rst @@ -0,0 +1,493 @@ +.. SPDX-License-Identifier: GPL-2.0 + +V4L2 sub-devices +---------------- + +Many drivers need to communicate with sub-devices. These devices can do all +sort of tasks, but most commonly they handle audio and/or video muxing, +encoding or decoding. For webcams common sub-devices are sensors and camera +controllers. + +Usually these are I2C devices, but not necessarily. In order to provide the +driver with a consistent interface to these sub-devices the +:c:type:`v4l2_subdev` struct (v4l2-subdev.h) was created. + +Each sub-device driver must have a :c:type:`v4l2_subdev` struct. This struct +can be stand-alone for simple sub-devices or it might be embedded in a larger +struct if more state information needs to be stored. Usually there is a +low-level device struct (e.g. ``i2c_client``) that contains the device data as +setup by the kernel. It is recommended to store that pointer in the private +data of :c:type:`v4l2_subdev` using :c:func:`v4l2_set_subdevdata`. That makes +it easy to go from a :c:type:`v4l2_subdev` to the actual low-level bus-specific +device data. + +You also need a way to go from the low-level struct to :c:type:`v4l2_subdev`. +For the common i2c_client struct the i2c_set_clientdata() call is used to store +a :c:type:`v4l2_subdev` pointer, for other buses you may have to use other +methods. + +Bridges might also need to store per-subdev private data, such as a pointer to +bridge-specific per-subdev private data. The :c:type:`v4l2_subdev` structure +provides host private data for that purpose that can be accessed with +:c:func:`v4l2_get_subdev_hostdata` and :c:func:`v4l2_set_subdev_hostdata`. + +From the bridge driver perspective, you load the sub-device module and somehow +obtain the :c:type:`v4l2_subdev` pointer. For i2c devices this is easy: you call +``i2c_get_clientdata()``. For other buses something similar needs to be done. +Helper functions exists for sub-devices on an I2C bus that do most of this +tricky work for you. + +Each :c:type:`v4l2_subdev` contains function pointers that sub-device drivers +can implement (or leave ``NULL`` if it is not applicable). Since sub-devices can +do so many different things and you do not want to end up with a huge ops struct +of which only a handful of ops are commonly implemented, the function pointers +are sorted according to category and each category has its own ops struct. + +The top-level ops struct contains pointers to the category ops structs, which +may be NULL if the subdev driver does not support anything from that category. + +It looks like this: + +.. code-block:: c + + struct v4l2_subdev_core_ops { + int (*log_status)(struct v4l2_subdev *sd); + int (*init)(struct v4l2_subdev *sd, u32 val); + ... + }; + + struct v4l2_subdev_tuner_ops { + ... + }; + + struct v4l2_subdev_audio_ops { + ... + }; + + struct v4l2_subdev_video_ops { + ... + }; + + struct v4l2_subdev_pad_ops { + ... + }; + + struct v4l2_subdev_ops { + const struct v4l2_subdev_core_ops *core; + const struct v4l2_subdev_tuner_ops *tuner; + const struct v4l2_subdev_audio_ops *audio; + const struct v4l2_subdev_video_ops *video; + const struct v4l2_subdev_pad_ops *video; + }; + +The core ops are common to all subdevs, the other categories are implemented +depending on the sub-device. E.g. a video device is unlikely to support the +audio ops and vice versa. + +This setup limits the number of function pointers while still making it easy +to add new ops and categories. + +A sub-device driver initializes the :c:type:`v4l2_subdev` struct using: + + :c:func:`v4l2_subdev_init <v4l2_subdev_init>` + (:c:type:`sd <v4l2_subdev>`, &\ :c:type:`ops <v4l2_subdev_ops>`). + + +Afterwards you need to initialize :c:type:`sd <v4l2_subdev>`->name with a +unique name and set the module owner. This is done for you if you use the +i2c helper functions. + +If integration with the media framework is needed, you must initialize the +:c:type:`media_entity` struct embedded in the :c:type:`v4l2_subdev` struct +(entity field) by calling :c:func:`media_entity_pads_init`, if the entity has +pads: + +.. code-block:: c + + struct media_pad *pads = &my_sd->pads; + int err; + + err = media_entity_pads_init(&sd->entity, npads, pads); + +The pads array must have been previously initialized. There is no need to +manually set the struct :c:type:`media_entity` function and name fields, but the +revision field must be initialized if needed. + +A reference to the entity will be automatically acquired/released when the +subdev device node (if any) is opened/closed. + +Don't forget to cleanup the media entity before the sub-device is destroyed: + +.. code-block:: c + + media_entity_cleanup(&sd->entity); + +If the subdev driver intends to process video and integrate with the media +framework, it must implement format related functionality using +:c:type:`v4l2_subdev_pad_ops` instead of :c:type:`v4l2_subdev_video_ops`. + +In that case, the subdev driver may set the link_validate field to provide +its own link validation function. The link validation function is called for +every link in the pipeline where both of the ends of the links are V4L2 +sub-devices. The driver is still responsible for validating the correctness +of the format configuration between sub-devices and video nodes. + +If link_validate op is not set, the default function +:c:func:`v4l2_subdev_link_validate_default` is used instead. This function +ensures that width, height and the media bus pixel code are equal on both source +and sink of the link. Subdev drivers are also free to use this function to +perform the checks mentioned above in addition to their own checks. + +There are currently two ways to register subdevices with the V4L2 core. The +first (traditional) possibility is to have subdevices registered by bridge +drivers. This can be done when the bridge driver has the complete information +about subdevices connected to it and knows exactly when to register them. This +is typically the case for internal subdevices, like video data processing units +within SoCs or complex PCI(e) boards, camera sensors in USB cameras or connected +to SoCs, which pass information about them to bridge drivers, usually in their +platform data. + +There are however also situations where subdevices have to be registered +asynchronously to bridge devices. An example of such a configuration is a Device +Tree based system where information about subdevices is made available to the +system independently from the bridge devices, e.g. when subdevices are defined +in DT as I2C device nodes. The API used in this second case is described further +below. + +Using one or the other registration method only affects the probing process, the +run-time bridge-subdevice interaction is in both cases the same. + +In the synchronous case a device (bridge) driver needs to register the +:c:type:`v4l2_subdev` with the v4l2_device: + + :c:func:`v4l2_device_register_subdev <v4l2_device_register_subdev>` + (:c:type:`v4l2_dev <v4l2_device>`, :c:type:`sd <v4l2_subdev>`). + +This can fail if the subdev module disappeared before it could be registered. +After this function was called successfully the subdev->dev field points to +the :c:type:`v4l2_device`. + +If the v4l2_device parent device has a non-NULL mdev field, the sub-device +entity will be automatically registered with the media device. + +You can unregister a sub-device using: + + :c:func:`v4l2_device_unregister_subdev <v4l2_device_unregister_subdev>` + (:c:type:`sd <v4l2_subdev>`). + + +Afterwards the subdev module can be unloaded and +:c:type:`sd <v4l2_subdev>`->dev == ``NULL``. + +You can call an ops function either directly: + +.. code-block:: c + + err = sd->ops->core->g_std(sd, &norm); + +but it is better and easier to use this macro: + +.. code-block:: c + + err = v4l2_subdev_call(sd, core, g_std, &norm); + +The macro will to the right ``NULL`` pointer checks and returns ``-ENODEV`` +if :c:type:`sd <v4l2_subdev>` is ``NULL``, ``-ENOIOCTLCMD`` if either +:c:type:`sd <v4l2_subdev>`->core or :c:type:`sd <v4l2_subdev>`->core->g_std is ``NULL``, or the actual result of the +:c:type:`sd <v4l2_subdev>`->ops->core->g_std ops. + +It is also possible to call all or a subset of the sub-devices: + +.. code-block:: c + + v4l2_device_call_all(v4l2_dev, 0, core, g_std, &norm); + +Any subdev that does not support this ops is skipped and error results are +ignored. If you want to check for errors use this: + +.. code-block:: c + + err = v4l2_device_call_until_err(v4l2_dev, 0, core, g_std, &norm); + +Any error except ``-ENOIOCTLCMD`` will exit the loop with that error. If no +errors (except ``-ENOIOCTLCMD``) occurred, then 0 is returned. + +The second argument to both calls is a group ID. If 0, then all subdevs are +called. If non-zero, then only those whose group ID match that value will +be called. Before a bridge driver registers a subdev it can set +:c:type:`sd <v4l2_subdev>`->grp_id to whatever value it wants (it's 0 by +default). This value is owned by the bridge driver and the sub-device driver +will never modify or use it. + +The group ID gives the bridge driver more control how callbacks are called. +For example, there may be multiple audio chips on a board, each capable of +changing the volume. But usually only one will actually be used when the +user want to change the volume. You can set the group ID for that subdev to +e.g. AUDIO_CONTROLLER and specify that as the group ID value when calling +``v4l2_device_call_all()``. That ensures that it will only go to the subdev +that needs it. + +If the sub-device needs to notify its v4l2_device parent of an event, then +it can call ``v4l2_subdev_notify(sd, notification, arg)``. This macro checks +whether there is a ``notify()`` callback defined and returns ``-ENODEV`` if not. +Otherwise the result of the ``notify()`` call is returned. + +The advantage of using :c:type:`v4l2_subdev` is that it is a generic struct and +does not contain any knowledge about the underlying hardware. So a driver might +contain several subdevs that use an I2C bus, but also a subdev that is +controlled through GPIO pins. This distinction is only relevant when setting +up the device, but once the subdev is registered it is completely transparent. + +In the asynchronous case subdevice probing can be invoked independently of the +bridge driver availability. The subdevice driver then has to verify whether all +the requirements for a successful probing are satisfied. This can include a +check for a master clock availability. If any of the conditions aren't satisfied +the driver might decide to return ``-EPROBE_DEFER`` to request further reprobing +attempts. Once all conditions are met the subdevice shall be registered using +the :c:func:`v4l2_async_register_subdev` function. Unregistration is +performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices +registered this way are stored in a global list of subdevices, ready to be +picked up by bridge drivers. + +Bridge drivers in turn have to register a notifier object. This is +performed using the :c:func:`v4l2_async_notifier_register` call. To +unregister the notifier the driver has to call +:c:func:`v4l2_async_notifier_unregister`. The former of the two functions +takes two arguments: a pointer to struct :c:type:`v4l2_device` and a +pointer to struct :c:type:`v4l2_async_notifier`. + +Before registering the notifier, bridge drivers must do two things: +first, the notifier must be initialized using the +:c:func:`v4l2_async_notifier_init`. Second, bridge drivers can then +begin to form a list of subdevice descriptors that the bridge device +needs for its operation. Subdevice descriptors are added to the notifier +using the :c:func:`v4l2_async_notifier_add_subdev` call. This function +takes two arguments: a pointer to struct :c:type:`v4l2_async_notifier`, +and a pointer to the subdevice descripter, which is of type struct +:c:type:`v4l2_async_subdev`. + +The V4L2 core will then use these descriptors to match asynchronously +registered subdevices to them. If a match is detected the ``.bound()`` +notifier callback is called. After all subdevices have been located the +.complete() callback is called. When a subdevice is removed from the +system the .unbind() method is called. All three callbacks are optional. + +V4L2 sub-device userspace API +----------------------------- + +Bridge drivers traditionally expose one or multiple video nodes to userspace, +and control subdevices through the :c:type:`v4l2_subdev_ops` operations in +response to video node operations. This hides the complexity of the underlying +hardware from applications. For complex devices, finer-grained control of the +device than what the video nodes offer may be required. In those cases, bridge +drivers that implement :ref:`the media controller API <media_controller>` may +opt for making the subdevice operations directly accessible from userpace. + +Device nodes named ``v4l-subdev``\ *X* can be created in ``/dev`` to access +sub-devices directly. If a sub-device supports direct userspace configuration +it must set the ``V4L2_SUBDEV_FL_HAS_DEVNODE`` flag before being registered. + +After registering sub-devices, the :c:type:`v4l2_device` driver can create +device nodes for all registered sub-devices marked with +``V4L2_SUBDEV_FL_HAS_DEVNODE`` by calling +:c:func:`v4l2_device_register_subdev_nodes`. Those device nodes will be +automatically removed when sub-devices are unregistered. + +The device node handles a subset of the V4L2 API. + +``VIDIOC_QUERYCTRL``, +``VIDIOC_QUERYMENU``, +``VIDIOC_G_CTRL``, +``VIDIOC_S_CTRL``, +``VIDIOC_G_EXT_CTRLS``, +``VIDIOC_S_EXT_CTRLS`` and +``VIDIOC_TRY_EXT_CTRLS``: + + The controls ioctls are identical to the ones defined in V4L2. They + behave identically, with the only exception that they deal only with + controls implemented in the sub-device. Depending on the driver, those + controls can be also be accessed through one (or several) V4L2 device + nodes. + +``VIDIOC_DQEVENT``, +``VIDIOC_SUBSCRIBE_EVENT`` and +``VIDIOC_UNSUBSCRIBE_EVENT`` + + The events ioctls are identical to the ones defined in V4L2. They + behave identically, with the only exception that they deal only with + events generated by the sub-device. Depending on the driver, those + events can also be reported by one (or several) V4L2 device nodes. + + Sub-device drivers that want to use events need to set the + ``V4L2_SUBDEV_USES_EVENTS`` :c:type:`v4l2_subdev`.flags and initialize + :c:type:`v4l2_subdev`.nevents to events queue depth before registering + the sub-device. After registration events can be queued as usual on the + :c:type:`v4l2_subdev`.devnode device node. + + To properly support events, the ``poll()`` file operation is also + implemented. + +Private ioctls + + All ioctls not in the above list are passed directly to the sub-device + driver through the core::ioctl operation. + +Read-only sub-device userspace API +---------------------------------- + +Bridge drivers that control their connected subdevices through direct calls to +the kernel API realized by :c:type:`v4l2_subdev_ops` structure do not usually +want userspace to be able to change the same parameters through the subdevice +device node and thus do not usually register any. + +It is sometimes useful to report to userspace the current subdevice +configuration through a read-only API, that does not permit applications to +change to the device parameters but allows interfacing to the subdevice device +node to inspect them. + +For instance, to implement cameras based on computational photography, userspace +needs to know the detailed camera sensor configuration (in terms of skipping, +binning, cropping and scaling) for each supported output resolution. To support +such use cases, bridge drivers may expose the subdevice operations to userspace +through a read-only API. + +To create a read-only device node for all the subdevices registered with the +``V4L2_SUBDEV_FL_HAS_DEVNODE`` set, the :c:type:`v4l2_device` driver should call +:c:func:`v4l2_device_register_ro_subdev_nodes`. + +Access to the following ioctls for userspace applications is restricted on +sub-device device nodes registered with +:c:func:`v4l2_device_register_ro_subdev_nodes`. + +``VIDIOC_SUBDEV_S_FMT``, +``VIDIOC_SUBDEV_S_CROP``, +``VIDIOC_SUBDEV_S_SELECTION``: + + These ioctls are only allowed on a read-only subdevice device node + for the :ref:`V4L2_SUBDEV_FORMAT_TRY <v4l2-subdev-format-whence>` + formats and selection rectangles. + +``VIDIOC_SUBDEV_S_FRAME_INTERVAL``, +``VIDIOC_SUBDEV_S_DV_TIMINGS``, +``VIDIOC_SUBDEV_S_STD``: + + These ioctls are not allowed on a read-only subdevice node. + +In case the ioctl is not allowed, or the format to modify is set to +``V4L2_SUBDEV_FORMAT_ACTIVE``, the core returns a negative error code and +the errno variable is set to ``-EPERM``. + +I2C sub-device drivers +---------------------- + +Since these drivers are so common, special helper functions are available to +ease the use of these drivers (``v4l2-common.h``). + +The recommended method of adding :c:type:`v4l2_subdev` support to an I2C driver +is to embed the :c:type:`v4l2_subdev` struct into the state struct that is +created for each I2C device instance. Very simple devices have no state +struct and in that case you can just create a :c:type:`v4l2_subdev` directly. + +A typical state struct would look like this (where 'chipname' is replaced by +the name of the chip): + +.. code-block:: c + + struct chipname_state { + struct v4l2_subdev sd; + ... /* additional state fields */ + }; + +Initialize the :c:type:`v4l2_subdev` struct as follows: + +.. code-block:: c + + v4l2_i2c_subdev_init(&state->sd, client, subdev_ops); + +This function will fill in all the fields of :c:type:`v4l2_subdev` ensure that +the :c:type:`v4l2_subdev` and i2c_client both point to one another. + +You should also add a helper inline function to go from a :c:type:`v4l2_subdev` +pointer to a chipname_state struct: + +.. code-block:: c + + static inline struct chipname_state *to_state(struct v4l2_subdev *sd) + { + return container_of(sd, struct chipname_state, sd); + } + +Use this to go from the :c:type:`v4l2_subdev` struct to the ``i2c_client`` +struct: + +.. code-block:: c + + struct i2c_client *client = v4l2_get_subdevdata(sd); + +And this to go from an ``i2c_client`` to a :c:type:`v4l2_subdev` struct: + +.. code-block:: c + + struct v4l2_subdev *sd = i2c_get_clientdata(client); + +Make sure to call +:c:func:`v4l2_device_unregister_subdev`\ (:c:type:`sd <v4l2_subdev>`) +when the ``remove()`` callback is called. This will unregister the sub-device +from the bridge driver. It is safe to call this even if the sub-device was +never registered. + +You need to do this because when the bridge driver destroys the i2c adapter +the ``remove()`` callbacks are called of the i2c devices on that adapter. +After that the corresponding v4l2_subdev structures are invalid, so they +have to be unregistered first. Calling +:c:func:`v4l2_device_unregister_subdev`\ (:c:type:`sd <v4l2_subdev>`) +from the ``remove()`` callback ensures that this is always done correctly. + + +The bridge driver also has some helper functions it can use: + +.. code-block:: c + + struct v4l2_subdev *sd = v4l2_i2c_new_subdev(v4l2_dev, adapter, + "module_foo", "chipid", 0x36, NULL); + +This loads the given module (can be ``NULL`` if no module needs to be loaded) +and calls :c:func:`i2c_new_device` with the given ``i2c_adapter`` and +chip/address arguments. If all goes well, then it registers the subdev with +the v4l2_device. + +You can also use the last argument of :c:func:`v4l2_i2c_new_subdev` to pass +an array of possible I2C addresses that it should probe. These probe addresses +are only used if the previous argument is 0. A non-zero argument means that you +know the exact i2c address so in that case no probing will take place. + +Both functions return ``NULL`` if something went wrong. + +Note that the chipid you pass to :c:func:`v4l2_i2c_new_subdev` is usually +the same as the module name. It allows you to specify a chip variant, e.g. +"saa7114" or "saa7115". In general though the i2c driver autodetects this. +The use of chipid is something that needs to be looked at more closely at a +later date. It differs between i2c drivers and as such can be confusing. +To see which chip variants are supported you can look in the i2c driver code +for the i2c_device_id table. This lists all the possibilities. + +There are one more helper function: + +:c:func:`v4l2_i2c_new_subdev_board` uses an :c:type:`i2c_board_info` struct +which is passed to the i2c driver and replaces the irq, platform_data and addr +arguments. + +If the subdev supports the s_config core ops, then that op is called with +the irq and platform_data arguments after the subdev was setup. + +The :c:func:`v4l2_i2c_new_subdev` function will call +:c:func:`v4l2_i2c_new_subdev_board`, internally filling a +:c:type:`i2c_board_info` structure using the ``client_type`` and the +``addr`` to fill it. + +V4L2 sub-device functions and data structures +--------------------------------------------- + +.. kernel-doc:: include/media/v4l2-subdev.h + +.. kernel-doc:: include/media/v4l2-async.h diff --git a/Documentation/driver-api/media/v4l2-tuner.rst b/Documentation/driver-api/media/v4l2-tuner.rst new file mode 100644 index 000000000000..e6caa3321566 --- /dev/null +++ b/Documentation/driver-api/media/v4l2-tuner.rst @@ -0,0 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Tuner functions and data structures +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. kernel-doc:: include/media/tuner.h + +.. kernel-doc:: include/media/tuner-types.h diff --git a/Documentation/driver-api/media/v4l2-tveeprom.rst b/Documentation/driver-api/media/v4l2-tveeprom.rst new file mode 100644 index 000000000000..43fb391edaba --- /dev/null +++ b/Documentation/driver-api/media/v4l2-tveeprom.rst @@ -0,0 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Hauppauge TV EEPROM functions and data structures +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. kernel-doc:: include/media/tveeprom.h diff --git a/Documentation/driver-api/media/v4l2-videobuf.rst b/Documentation/driver-api/media/v4l2-videobuf.rst new file mode 100644 index 000000000000..4b1d84eefeb8 --- /dev/null +++ b/Documentation/driver-api/media/v4l2-videobuf.rst @@ -0,0 +1,403 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _vb_framework: + +Videobuf Framework +================== + +Author: Jonathan Corbet <corbet@lwn.net> + +Current as of 2.6.33 + +.. note:: + + The videobuf framework was deprecated in favor of videobuf2. Shouldn't + be used on new drivers. + +Introduction +------------ + +The videobuf layer functions as a sort of glue layer between a V4L2 driver +and user space. It handles the allocation and management of buffers for +the storage of video frames. There is a set of functions which can be used +to implement many of the standard POSIX I/O system calls, including read(), +poll(), and, happily, mmap(). Another set of functions can be used to +implement the bulk of the V4L2 ioctl() calls related to streaming I/O, +including buffer allocation, queueing and dequeueing, and streaming +control. Using videobuf imposes a few design decisions on the driver +author, but the payback comes in the form of reduced code in the driver and +a consistent implementation of the V4L2 user-space API. + +Buffer types +------------ + +Not all video devices use the same kind of buffers. In fact, there are (at +least) three common variations: + + - Buffers which are scattered in both the physical and (kernel) virtual + address spaces. (Almost) all user-space buffers are like this, but it + makes great sense to allocate kernel-space buffers this way as well when + it is possible. Unfortunately, it is not always possible; working with + this kind of buffer normally requires hardware which can do + scatter/gather DMA operations. + + - Buffers which are physically scattered, but which are virtually + contiguous; buffers allocated with vmalloc(), in other words. These + buffers are just as hard to use for DMA operations, but they can be + useful in situations where DMA is not available but virtually-contiguous + buffers are convenient. + + - Buffers which are physically contiguous. Allocation of this kind of + buffer can be unreliable on fragmented systems, but simpler DMA + controllers cannot deal with anything else. + +Videobuf can work with all three types of buffers, but the driver author +must pick one at the outset and design the driver around that decision. + +[It's worth noting that there's a fourth kind of buffer: "overlay" buffers +which are located within the system's video memory. The overlay +functionality is considered to be deprecated for most use, but it still +shows up occasionally in system-on-chip drivers where the performance +benefits merit the use of this technique. Overlay buffers can be handled +as a form of scattered buffer, but there are very few implementations in +the kernel and a description of this technique is currently beyond the +scope of this document.] + +Data structures, callbacks, and initialization +---------------------------------------------- + +Depending on which type of buffers are being used, the driver should +include one of the following files: + +.. code-block:: none + + <media/videobuf-dma-sg.h> /* Physically scattered */ + <media/videobuf-vmalloc.h> /* vmalloc() buffers */ + <media/videobuf-dma-contig.h> /* Physically contiguous */ + +The driver's data structure describing a V4L2 device should include a +struct videobuf_queue instance for the management of the buffer queue, +along with a list_head for the queue of available buffers. There will also +need to be an interrupt-safe spinlock which is used to protect (at least) +the queue. + +The next step is to write four simple callbacks to help videobuf deal with +the management of buffers: + +.. code-block:: none + + struct videobuf_queue_ops { + int (*buf_setup)(struct videobuf_queue *q, + unsigned int *count, unsigned int *size); + int (*buf_prepare)(struct videobuf_queue *q, + struct videobuf_buffer *vb, + enum v4l2_field field); + void (*buf_queue)(struct videobuf_queue *q, + struct videobuf_buffer *vb); + void (*buf_release)(struct videobuf_queue *q, + struct videobuf_buffer *vb); + }; + +buf_setup() is called early in the I/O process, when streaming is being +initiated; its purpose is to tell videobuf about the I/O stream. The count +parameter will be a suggested number of buffers to use; the driver should +check it for rationality and adjust it if need be. As a practical rule, a +minimum of two buffers are needed for proper streaming, and there is +usually a maximum (which cannot exceed 32) which makes sense for each +device. The size parameter should be set to the expected (maximum) size +for each frame of data. + +Each buffer (in the form of a struct videobuf_buffer pointer) will be +passed to buf_prepare(), which should set the buffer's size, width, height, +and field fields properly. If the buffer's state field is +VIDEOBUF_NEEDS_INIT, the driver should pass it to: + +.. code-block:: none + + int videobuf_iolock(struct videobuf_queue* q, struct videobuf_buffer *vb, + struct v4l2_framebuffer *fbuf); + +Among other things, this call will usually allocate memory for the buffer. +Finally, the buf_prepare() function should set the buffer's state to +VIDEOBUF_PREPARED. + +When a buffer is queued for I/O, it is passed to buf_queue(), which should +put it onto the driver's list of available buffers and set its state to +VIDEOBUF_QUEUED. Note that this function is called with the queue spinlock +held; if it tries to acquire it as well things will come to a screeching +halt. Yes, this is the voice of experience. Note also that videobuf may +wait on the first buffer in the queue; placing other buffers in front of it +could again gum up the works. So use list_add_tail() to enqueue buffers. + +Finally, buf_release() is called when a buffer is no longer intended to be +used. The driver should ensure that there is no I/O active on the buffer, +then pass it to the appropriate free routine(s): + +.. code-block:: none + + /* Scatter/gather drivers */ + int videobuf_dma_unmap(struct videobuf_queue *q, + struct videobuf_dmabuf *dma); + int videobuf_dma_free(struct videobuf_dmabuf *dma); + + /* vmalloc drivers */ + void videobuf_vmalloc_free (struct videobuf_buffer *buf); + + /* Contiguous drivers */ + void videobuf_dma_contig_free(struct videobuf_queue *q, + struct videobuf_buffer *buf); + +One way to ensure that a buffer is no longer under I/O is to pass it to: + +.. code-block:: none + + int videobuf_waiton(struct videobuf_buffer *vb, int non_blocking, int intr); + +Here, vb is the buffer, non_blocking indicates whether non-blocking I/O +should be used (it should be zero in the buf_release() case), and intr +controls whether an interruptible wait is used. + +File operations +--------------- + +At this point, much of the work is done; much of the rest is slipping +videobuf calls into the implementation of the other driver callbacks. The +first step is in the open() function, which must initialize the +videobuf queue. The function to use depends on the type of buffer used: + +.. code-block:: none + + void videobuf_queue_sg_init(struct videobuf_queue *q, + struct videobuf_queue_ops *ops, + struct device *dev, + spinlock_t *irqlock, + enum v4l2_buf_type type, + enum v4l2_field field, + unsigned int msize, + void *priv); + + void videobuf_queue_vmalloc_init(struct videobuf_queue *q, + struct videobuf_queue_ops *ops, + struct device *dev, + spinlock_t *irqlock, + enum v4l2_buf_type type, + enum v4l2_field field, + unsigned int msize, + void *priv); + + void videobuf_queue_dma_contig_init(struct videobuf_queue *q, + struct videobuf_queue_ops *ops, + struct device *dev, + spinlock_t *irqlock, + enum v4l2_buf_type type, + enum v4l2_field field, + unsigned int msize, + void *priv); + +In each case, the parameters are the same: q is the queue structure for the +device, ops is the set of callbacks as described above, dev is the device +structure for this video device, irqlock is an interrupt-safe spinlock to +protect access to the data structures, type is the buffer type used by the +device (cameras will use V4L2_BUF_TYPE_VIDEO_CAPTURE, for example), field +describes which field is being captured (often V4L2_FIELD_NONE for +progressive devices), msize is the size of any containing structure used +around struct videobuf_buffer, and priv is a private data pointer which +shows up in the priv_data field of struct videobuf_queue. Note that these +are void functions which, evidently, are immune to failure. + +V4L2 capture drivers can be written to support either of two APIs: the +read() system call and the rather more complicated streaming mechanism. As +a general rule, it is necessary to support both to ensure that all +applications have a chance of working with the device. Videobuf makes it +easy to do that with the same code. To implement read(), the driver need +only make a call to one of: + +.. code-block:: none + + ssize_t videobuf_read_one(struct videobuf_queue *q, + char __user *data, size_t count, + loff_t *ppos, int nonblocking); + + ssize_t videobuf_read_stream(struct videobuf_queue *q, + char __user *data, size_t count, + loff_t *ppos, int vbihack, int nonblocking); + +Either one of these functions will read frame data into data, returning the +amount actually read; the difference is that videobuf_read_one() will only +read a single frame, while videobuf_read_stream() will read multiple frames +if they are needed to satisfy the count requested by the application. A +typical driver read() implementation will start the capture engine, call +one of the above functions, then stop the engine before returning (though a +smarter implementation might leave the engine running for a little while in +anticipation of another read() call happening in the near future). + +The poll() function can usually be implemented with a direct call to: + +.. code-block:: none + + unsigned int videobuf_poll_stream(struct file *file, + struct videobuf_queue *q, + poll_table *wait); + +Note that the actual wait queue eventually used will be the one associated +with the first available buffer. + +When streaming I/O is done to kernel-space buffers, the driver must support +the mmap() system call to enable user space to access the data. In many +V4L2 drivers, the often-complex mmap() implementation simplifies to a +single call to: + +.. code-block:: none + + int videobuf_mmap_mapper(struct videobuf_queue *q, + struct vm_area_struct *vma); + +Everything else is handled by the videobuf code. + +The release() function requires two separate videobuf calls: + +.. code-block:: none + + void videobuf_stop(struct videobuf_queue *q); + int videobuf_mmap_free(struct videobuf_queue *q); + +The call to videobuf_stop() terminates any I/O in progress - though it is +still up to the driver to stop the capture engine. The call to +videobuf_mmap_free() will ensure that all buffers have been unmapped; if +so, they will all be passed to the buf_release() callback. If buffers +remain mapped, videobuf_mmap_free() returns an error code instead. The +purpose is clearly to cause the closing of the file descriptor to fail if +buffers are still mapped, but every driver in the 2.6.32 kernel cheerfully +ignores its return value. + +ioctl() operations +------------------ + +The V4L2 API includes a very long list of driver callbacks to respond to +the many ioctl() commands made available to user space. A number of these +- those associated with streaming I/O - turn almost directly into videobuf +calls. The relevant helper functions are: + +.. code-block:: none + + int videobuf_reqbufs(struct videobuf_queue *q, + struct v4l2_requestbuffers *req); + int videobuf_querybuf(struct videobuf_queue *q, struct v4l2_buffer *b); + int videobuf_qbuf(struct videobuf_queue *q, struct v4l2_buffer *b); + int videobuf_dqbuf(struct videobuf_queue *q, struct v4l2_buffer *b, + int nonblocking); + int videobuf_streamon(struct videobuf_queue *q); + int videobuf_streamoff(struct videobuf_queue *q); + +So, for example, a VIDIOC_REQBUFS call turns into a call to the driver's +vidioc_reqbufs() callback which, in turn, usually only needs to locate the +proper struct videobuf_queue pointer and pass it to videobuf_reqbufs(). +These support functions can replace a great deal of buffer management +boilerplate in a lot of V4L2 drivers. + +The vidioc_streamon() and vidioc_streamoff() functions will be a bit more +complex, of course, since they will also need to deal with starting and +stopping the capture engine. + +Buffer allocation +----------------- + +Thus far, we have talked about buffers, but have not looked at how they are +allocated. The scatter/gather case is the most complex on this front. For +allocation, the driver can leave buffer allocation entirely up to the +videobuf layer; in this case, buffers will be allocated as anonymous +user-space pages and will be very scattered indeed. If the application is +using user-space buffers, no allocation is needed; the videobuf layer will +take care of calling get_user_pages() and filling in the scatterlist array. + +If the driver needs to do its own memory allocation, it should be done in +the vidioc_reqbufs() function, *after* calling videobuf_reqbufs(). The +first step is a call to: + +.. code-block:: none + + struct videobuf_dmabuf *videobuf_to_dma(struct videobuf_buffer *buf); + +The returned videobuf_dmabuf structure (defined in +<media/videobuf-dma-sg.h>) includes a couple of relevant fields: + +.. code-block:: none + + struct scatterlist *sglist; + int sglen; + +The driver must allocate an appropriately-sized scatterlist array and +populate it with pointers to the pieces of the allocated buffer; sglen +should be set to the length of the array. + +Drivers using the vmalloc() method need not (and cannot) concern themselves +with buffer allocation at all; videobuf will handle those details. The +same is normally true of contiguous-DMA drivers as well; videobuf will +allocate the buffers (with dma_alloc_coherent()) when it sees fit. That +means that these drivers may be trying to do high-order allocations at any +time, an operation which is not always guaranteed to work. Some drivers +play tricks by allocating DMA space at system boot time; videobuf does not +currently play well with those drivers. + +As of 2.6.31, contiguous-DMA drivers can work with a user-supplied buffer, +as long as that buffer is physically contiguous. Normal user-space +allocations will not meet that criterion, but buffers obtained from other +kernel drivers, or those contained within huge pages, will work with these +drivers. + +Filling the buffers +------------------- + +The final part of a videobuf implementation has no direct callback - it's +the portion of the code which actually puts frame data into the buffers, +usually in response to interrupts from the device. For all types of +drivers, this process works approximately as follows: + + - Obtain the next available buffer and make sure that somebody is actually + waiting for it. + + - Get a pointer to the memory and put video data there. + + - Mark the buffer as done and wake up the process waiting for it. + +Step (1) above is done by looking at the driver-managed list_head structure +- the one which is filled in the buf_queue() callback. Because starting +the engine and enqueueing buffers are done in separate steps, it's possible +for the engine to be running without any buffers available - in the +vmalloc() case especially. So the driver should be prepared for the list +to be empty. It is equally possible that nobody is yet interested in the +buffer; the driver should not remove it from the list or fill it until a +process is waiting on it. That test can be done by examining the buffer's +done field (a wait_queue_head_t structure) with waitqueue_active(). + +A buffer's state should be set to VIDEOBUF_ACTIVE before being mapped for +DMA; that ensures that the videobuf layer will not try to do anything with +it while the device is transferring data. + +For scatter/gather drivers, the needed memory pointers will be found in the +scatterlist structure described above. Drivers using the vmalloc() method +can get a memory pointer with: + +.. code-block:: none + + void *videobuf_to_vmalloc(struct videobuf_buffer *buf); + +For contiguous DMA drivers, the function to use is: + +.. code-block:: none + + dma_addr_t videobuf_to_dma_contig(struct videobuf_buffer *buf); + +The contiguous DMA API goes out of its way to hide the kernel-space address +of the DMA buffer from drivers. + +The final step is to set the size field of the relevant videobuf_buffer +structure to the actual size of the captured image, set state to +VIDEOBUF_DONE, then call wake_up() on the done queue. At this point, the +buffer is owned by the videobuf layer and the driver should not touch it +again. + +Developers who are interested in more information can go into the relevant +header files; there are a few low-level functions declared there which have +not been talked about here. Note also that all of these calls are exported +GPL-only, so they will not be available to non-GPL kernel modules. diff --git a/Documentation/driver-api/media/v4l2-videobuf2.rst b/Documentation/driver-api/media/v4l2-videobuf2.rst new file mode 100644 index 000000000000..1044f64ff168 --- /dev/null +++ b/Documentation/driver-api/media/v4l2-videobuf2.rst @@ -0,0 +1,12 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _vb2_framework: + +V4L2 videobuf2 functions and data structures +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. kernel-doc:: include/media/videobuf2-core.h + +.. kernel-doc:: include/media/videobuf2-v4l2.h + +.. kernel-doc:: include/media/videobuf2-memops.h diff --git a/Documentation/driver-api/nvdimm/nvdimm.rst b/Documentation/driver-api/nvdimm/nvdimm.rst index 08f855cbb4e6..79c0fd39f2af 100644 --- a/Documentation/driver-api/nvdimm/nvdimm.rst +++ b/Documentation/driver-api/nvdimm/nvdimm.rst @@ -278,8 +278,8 @@ by a region device with a dynamically assigned id (REGION0 - REGION5). be contiguous in DPA-space. This bus is provided by the kernel under the device - /sys/devices/platform/nfit_test.0 when CONFIG_NFIT_TEST is enabled and - the nfit_test.ko module is loaded. This not only test LIBNVDIMM but the + /sys/devices/platform/nfit_test.0 when the nfit_test.ko module from + tools/testing/nvdimm is loaded. This not only test LIBNVDIMM but the acpi_nfit.ko driver as well. diff --git a/Documentation/driver-api/pm/cpuidle.rst b/Documentation/driver-api/pm/cpuidle.rst index 006cf6db40c6..3588bf078566 100644 --- a/Documentation/driver-api/pm/cpuidle.rst +++ b/Documentation/driver-api/pm/cpuidle.rst @@ -68,9 +68,8 @@ only one in the list (that is, the list was empty before) or the value of its governor currently in use, or the name of the new governor was passed to the kernel as the value of the ``cpuidle.governor=`` command line parameter, the new governor will be used from that point on (there can be only one ``CPUIdle`` -governor in use at a time). Also, if ``cpuidle_sysfs_switch`` is passed to the -kernel in the command line, user space can choose the ``CPUIdle`` governor to -use at run time via ``sysfs``. +governor in use at a time). Also, user space can choose the ``CPUIdle`` +governor to use at run time via ``sysfs``. Once registered, ``CPUIdle`` governors cannot be unregistered, so it is not practical to put them into loadable kernel modules. diff --git a/Documentation/driver-api/pm/devices.rst b/Documentation/driver-api/pm/devices.rst index f66c7b9126ea..946ad0b94e31 100644 --- a/Documentation/driver-api/pm/devices.rst +++ b/Documentation/driver-api/pm/devices.rst @@ -349,7 +349,7 @@ the phases are: ``prepare``, ``suspend``, ``suspend_late``, ``suspend_noirq``. PM core will skip the ``suspend``, ``suspend_late`` and ``suspend_noirq`` phases as well as all of the corresponding phases of the subsequent device resume for all of these devices. In that case, - the ``->complete`` callback will be invoked directly after the + the ``->complete`` callback will be the next one invoked after the ``->prepare`` callback and is entirely responsible for putting the device into a consistent state as appropriate. @@ -361,9 +361,9 @@ the phases are: ``prepare``, ``suspend``, ``suspend_late``, ``suspend_noirq``. runtime PM disabled. This feature also can be controlled by device drivers by using the - ``DPM_FLAG_NEVER_SKIP`` and ``DPM_FLAG_SMART_PREPARE`` driver power - management flags. [Typically, they are set at the time the driver is - probed against the device in question by passing them to the + ``DPM_FLAG_NO_DIRECT_COMPLETE`` and ``DPM_FLAG_SMART_PREPARE`` driver + power management flags. [Typically, they are set at the time the driver + is probed against the device in question by passing them to the :c:func:`dev_pm_set_driver_flags` helper function.] If the first of these flags is set, the PM core will not apply the direct-complete procedure described above to the given device and, consequenty, to any @@ -383,11 +383,15 @@ the phases are: ``prepare``, ``suspend``, ``suspend_late``, ``suspend_noirq``. ``->suspend`` methods provided by subsystems (bus types and PM domains in particular) must follow an additional rule regarding what can be done to the devices before their drivers' ``->suspend`` methods are called. - Namely, they can only resume the devices from runtime suspend by - calling :c:func:`pm_runtime_resume` for them, if that is necessary, and + Namely, they may resume the devices from runtime suspend by + calling :c:func:`pm_runtime_resume` for them, if that is necessary, but they must not update the state of the devices in any other way at that time (in case the drivers need to resume the devices from runtime - suspend in their ``->suspend`` methods). + suspend in their ``->suspend`` methods). In fact, the PM core prevents + subsystems or drivers from putting devices into runtime suspend at + these times by calling :c:func:`pm_runtime_get_noresume` before issuing + the ``->prepare`` callback (and calling :c:func:`pm_runtime_put` after + issuing the ``->complete`` callback). 3. For a number of devices it is convenient to split suspend into the "quiesce device" and "save device state" phases, in which cases @@ -459,22 +463,22 @@ When resuming from freeze, standby or memory sleep, the phases are: Note, however, that new children may be registered below the device as soon as the ``->resume`` callbacks occur; it's not necessary to wait - until the ``complete`` phase with that. + until the ``complete`` phase runs. Moreover, if the preceding ``->prepare`` callback returned a positive number, the device may have been left in runtime suspend throughout the - whole system suspend and resume (the ``suspend``, ``suspend_late``, - ``suspend_noirq`` phases of system suspend and the ``resume_noirq``, - ``resume_early``, ``resume`` phases of system resume may have been - skipped for it). In that case, the ``->complete`` callback is entirely + whole system suspend and resume (its ``->suspend``, ``->suspend_late``, + ``->suspend_noirq``, ``->resume_noirq``, + ``->resume_early``, and ``->resume`` callbacks may have been + skipped). In that case, the ``->complete`` callback is entirely responsible for putting the device into a consistent state after system suspend if necessary. [For example, it may need to queue up a runtime resume request for the device for this purpose.] To check if that is the case, the ``->complete`` callback can consult the device's - ``power.direct_complete`` flag. Namely, if that flag is set when the - ``->complete`` callback is being run, it has been called directly after - the preceding ``->prepare`` and special actions may be required - to make the device work correctly afterward. + ``power.direct_complete`` flag. If that flag is set when the + ``->complete`` callback is being run then the direct-complete mechanism + was used, and special actions may be required to make the device work + correctly afterward. At the end of these phases, drivers should be as functional as they were before suspending: I/O can be performed using DMA and IRQs, and the relevant clocks are @@ -575,10 +579,12 @@ and the phases are similar. The ``->poweroff``, ``->poweroff_late`` and ``->poweroff_noirq`` callbacks should do essentially the same things as the ``->suspend``, ``->suspend_late`` -and ``->suspend_noirq`` callbacks, respectively. The only notable difference is +and ``->suspend_noirq`` callbacks, respectively. A notable difference is that they need not store the device register values, because the registers should already have been stored during the ``freeze``, ``freeze_late`` or -``freeze_noirq`` phases. +``freeze_noirq`` phases. Also, on many machines the firmware will power-down +the entire system, so it is not necessary for the callback to put the device in +a low-power state. Leaving Hibernation @@ -764,70 +770,119 @@ device driver in question. If it is necessary to resume a device from runtime suspend during a system-wide transition into a sleep state, that can be done by calling -:c:func:`pm_runtime_resume` for it from the ``->suspend`` callback (or its -couterpart for transitions related to hibernation) of either the device's driver -or a subsystem responsible for it (for example, a bus type or a PM domain). -That is guaranteed to work by the requirement that subsystems must not change -the state of devices (possibly except for resuming them from runtime suspend) +:c:func:`pm_runtime_resume` from the ``->suspend`` callback (or the ``->freeze`` +or ``->poweroff`` callback for transitions related to hibernation) of either the +device's driver or its subsystem (for example, a bus type or a PM domain). +However, subsystems must not otherwise change the runtime status of devices from their ``->prepare`` and ``->suspend`` callbacks (or equivalent) *before* invoking device drivers' ``->suspend`` callbacks (or equivalent). +.. _smart_suspend_flag: + +The ``DPM_FLAG_SMART_SUSPEND`` Driver Flag +------------------------------------------ + Some bus types and PM domains have a policy to resume all devices from runtime suspend upfront in their ``->suspend`` callbacks, but that may not be really -necessary if the driver of the device can cope with runtime-suspended devices. -The driver can indicate that by setting ``DPM_FLAG_SMART_SUSPEND`` in -:c:member:`power.driver_flags` at the probe time, by passing it to the -:c:func:`dev_pm_set_driver_flags` helper. That also may cause middle-layer code +necessary if the device's driver can cope with runtime-suspended devices. +The driver can indicate this by setting ``DPM_FLAG_SMART_SUSPEND`` in +:c:member:`power.driver_flags` at probe time, with the assistance of the +:c:func:`dev_pm_set_driver_flags` helper routine. + +Setting that flag causes the PM core and middle-layer code (bus types, PM domains etc.) to skip the ``->suspend_late`` and ``->suspend_noirq`` callbacks provided by the driver if the device remains in -runtime suspend at the beginning of the ``suspend_late`` phase of system-wide -suspend (or in the ``poweroff_late`` phase of hibernation), when runtime PM -has been disabled for it, under the assumption that its state should not change -after that point until the system-wide transition is over (the PM core itself -does that for devices whose "noirq", "late" and "early" system-wide PM callbacks -are executed directly by it). If that happens, the driver's system-wide resume -callbacks, if present, may still be invoked during the subsequent system-wide -resume transition and the device's runtime power management status may be set -to "active" before enabling runtime PM for it, so the driver must be prepared to -cope with the invocation of its system-wide resume callbacks back-to-back with -its ``->runtime_suspend`` one (without the intervening ``->runtime_resume`` and -so on) and the final state of the device must reflect the "active" runtime PM -status in that case. +runtime suspend throughout those phases of the system-wide suspend (and +similarly for the "freeze" and "poweroff" parts of system hibernation). +[Otherwise the same driver +callback might be executed twice in a row for the same device, which would not +be valid in general.] If the middle-layer system-wide PM callbacks are present +for the device then they are responsible for skipping these driver callbacks; +if not then the PM core skips them. The subsystem callback routines can +determine whether they need to skip the driver callbacks by testing the return +value from the :c:func:`dev_pm_skip_suspend` helper function. + +In addition, with ``DPM_FLAG_SMART_SUSPEND`` set, the driver's ``->thaw_noirq`` +and ``->thaw_early`` callbacks are skipped in hibernation if the device remained +in runtime suspend throughout the preceding "freeze" transition. Again, if the +middle-layer callbacks are present for the device, they are responsible for +doing this, otherwise the PM core takes care of it. + + +The ``DPM_FLAG_MAY_SKIP_RESUME`` Driver Flag +-------------------------------------------- During system-wide resume from a sleep state it's easiest to put devices into the full-power state, as explained in :file:`Documentation/power/runtime_pm.rst`. [Refer to that document for more information regarding this particular issue as well as for information on the device runtime power management framework in -general.] - -However, it often is desirable to leave devices in suspend after system -transitions to the working state, especially if those devices had been in +general.] However, it often is desirable to leave devices in suspend after +system transitions to the working state, especially if those devices had been in runtime suspend before the preceding system-wide suspend (or analogous) -transition. Device drivers can use the ``DPM_FLAG_LEAVE_SUSPENDED`` flag to -indicate to the PM core (and middle-layer code) that they prefer the specific -devices handled by them to be left suspended and they have no problems with -skipping their system-wide resume callbacks for this reason. Whether or not the -devices will actually be left in suspend may depend on their state before the -given system suspend-resume cycle and on the type of the system transition under -way. In particular, devices are not left suspended if that transition is a -restore from hibernation, as device states are not guaranteed to be reflected -by the information stored in the hibernation image in that case. - -The middle-layer code involved in the handling of the device is expected to -indicate to the PM core if the device may be left in suspend by setting its -:c:member:`power.may_skip_resume` status bit which is checked by the PM core -during the "noirq" phase of the preceding system-wide suspend (or analogous) -transition. The middle layer is then responsible for handling the device as -appropriate in its "noirq" resume callback, which is executed regardless of -whether or not the device is left suspended, but the other resume callbacks -(except for ``->complete``) will be skipped automatically by the PM core if the -device really can be left in suspend. - -For devices whose "noirq", "late" and "early" driver callbacks are invoked -directly by the PM core, all of the system-wide resume callbacks are skipped if -``DPM_FLAG_LEAVE_SUSPENDED`` is set and the device is in runtime suspend during -the ``suspend_noirq`` (or analogous) phase or the transition under way is a -proper system suspend (rather than anything related to hibernation) and the -device's wakeup settings are suitable for runtime PM (that is, it cannot -generate wakeup signals at all or it is allowed to wake up the system from -sleep). +transition. + +To that end, device drivers can use the ``DPM_FLAG_MAY_SKIP_RESUME`` flag to +indicate to the PM core and middle-layer code that they allow their "noirq" and +"early" resume callbacks to be skipped if the device can be left in suspend +after system-wide PM transitions to the working state. Whether or not that is +the case generally depends on the state of the device before the given system +suspend-resume cycle and on the type of the system transition under way. +In particular, the "thaw" and "restore" transitions related to hibernation are +not affected by ``DPM_FLAG_MAY_SKIP_RESUME`` at all. [All callbacks are +issued during the "restore" transition regardless of the flag settings, +and whether or not any driver callbacks +are skipped during the "thaw" transition depends whether or not the +``DPM_FLAG_SMART_SUSPEND`` flag is set (see `above <smart_suspend_flag_>`_). +In addition, a device is not allowed to remain in runtime suspend if any of its +children will be returned to full power.] + +The ``DPM_FLAG_MAY_SKIP_RESUME`` flag is taken into account in combination with +the :c:member:`power.may_skip_resume` status bit set by the PM core during the +"suspend" phase of suspend-type transitions. If the driver or the middle layer +has a reason to prevent the driver's "noirq" and "early" resume callbacks from +being skipped during the subsequent system resume transition, it should +clear :c:member:`power.may_skip_resume` in its ``->suspend``, ``->suspend_late`` +or ``->suspend_noirq`` callback. [Note that the drivers setting +``DPM_FLAG_SMART_SUSPEND`` need to clear :c:member:`power.may_skip_resume` in +their ``->suspend`` callback in case the other two are skipped.] + +Setting the :c:member:`power.may_skip_resume` status bit along with the +``DPM_FLAG_MAY_SKIP_RESUME`` flag is necessary, but generally not sufficient, +for the driver's "noirq" and "early" resume callbacks to be skipped. Whether or +not they should be skipped can be determined by evaluating the +:c:func:`dev_pm_skip_resume` helper function. + +If that function returns ``true``, the driver's "noirq" and "early" resume +callbacks should be skipped and the device's runtime PM status will be set to +"suspended" by the PM core. Otherwise, if the device was runtime-suspended +during the preceding system-wide suspend transition and its +``DPM_FLAG_SMART_SUSPEND`` is set, its runtime PM status will be set to +"active" by the PM core. [Hence, the drivers that do not set +``DPM_FLAG_SMART_SUSPEND`` should not expect the runtime PM status of their +devices to be changed from "suspended" to "active" by the PM core during +system-wide resume-type transitions.] + +If the ``DPM_FLAG_MAY_SKIP_RESUME`` flag is not set for a device, but +``DPM_FLAG_SMART_SUSPEND`` is set and the driver's "late" and "noirq" suspend +callbacks are skipped, its system-wide "noirq" and "early" resume callbacks, if +present, are invoked as usual and the device's runtime PM status is set to +"active" by the PM core before enabling runtime PM for it. In that case, the +driver must be prepared to cope with the invocation of its system-wide resume +callbacks back-to-back with its ``->runtime_suspend`` one (without the +intervening ``->runtime_resume`` and system-wide suspend callbacks) and the +final state of the device must reflect the "active" runtime PM status in that +case. [Note that this is not a problem at all if the driver's +``->suspend_late`` callback pointer points to the same function as its +``->runtime_suspend`` one and its ``->resume_early`` callback pointer points to +the same function as the ``->runtime_resume`` one, while none of the other +system-wide suspend-resume callbacks of the driver are present, for example.] + +Likewise, if ``DPM_FLAG_MAY_SKIP_RESUME`` is set for a device, its driver's +system-wide "noirq" and "early" resume callbacks may be skipped while its "late" +and "noirq" suspend callbacks may have been executed (in principle, regardless +of whether or not ``DPM_FLAG_SMART_SUSPEND`` is set). In that case, the driver +needs to be able to cope with the invocation of its ``->runtime_resume`` +callback back-to-back with its "late" and "noirq" suspend ones. [For instance, +that is not a concern if the driver sets both ``DPM_FLAG_SMART_SUSPEND`` and +``DPM_FLAG_MAY_SKIP_RESUME`` and uses the same pair of suspend/resume callback +functions for runtime PM and system-wide suspend/resume.] diff --git a/Documentation/driver-api/thermal/cpu-idle-cooling.rst b/Documentation/driver-api/thermal/cpu-idle-cooling.rst index a1c3edecae00..b9f34ceb2a38 100644 --- a/Documentation/driver-api/thermal/cpu-idle-cooling.rst +++ b/Documentation/driver-api/thermal/cpu-idle-cooling.rst @@ -1,3 +1,6 @@ +================ +CPU Idle Cooling +================ Situation: ---------- diff --git a/Documentation/driver-api/thermal/index.rst b/Documentation/driver-api/thermal/index.rst index 5ba61d19c6ae..4cb0b9b6bfb8 100644 --- a/Documentation/driver-api/thermal/index.rst +++ b/Documentation/driver-api/thermal/index.rst @@ -8,6 +8,7 @@ Thermal :maxdepth: 1 cpu-cooling-api + cpu-idle-cooling sysfs-api power_allocator |