.. SPDX-License-Identifier: CC-BY-SA-4.0 .. _coding-style-guidelines: Coding Style Guidelines ======================= These coding guidelines are meant to ensure code quality. As a contributor you are expected to follow them in all code submitted to the project. While strict compliance is desired, exceptions are tolerated when justified with good reasons. Please read the whole coding guidelines and use common sense to decide when departing from them is appropriate. libcamera is written in C++, a language that has seen many revisions and offers an extensive set of features that are easy to abuse. These coding guidelines establish the subset of C++ used by the project. Coding Style ------------ Even if the programming language in use is different, the project embraces the `Linux Kernel Coding Style`_ with a few exception and some C++ specificities. .. _Linux Kernel Coding Style: https://www.kernel.org/doc/html/latest/process/coding-style.html In particular, from the kernel style document, the following section are adopted: * 1 "Indentation" * 2 "Breaking Long Lines" striving to fit code within 80 columns and accepting up to 120 columns when necessary * 3 "Placing Braces and Spaces" * 3.1 "Spaces" * 8 "Commenting" with the exception that in-function comments are not always un-welcome. While libcamera uses the kernel coding style for all typographic matters, the project is a user space library, developed in a different programming language, and the kernel guidelines fall short for this use case. For this reason, rules and guidelines from the `Google C++ Style Guide`_ have been adopted as well as most coding principles specified therein, with a few exceptions and relaxed limitations on some subjects. .. _Google C++ Style Guide: https://google.github.io/styleguide/cppguide.html The following exceptions apply to the naming conventions specified in the document: * File names: libcamera uses the .cpp extensions for C++ source files and the .h extension for header files * Variables, function parameters, function names and class members use camel case style, with the first letter in lower-case (as in 'camelCase' and not 'CamelCase') * Types (classes, structs, type aliases, and type template parameters) use camel case, with the first letter in capital case (as in 'CamelCase' and not 'camelCase') * Enum members use 'CamelCase', while macros are in capital case with underscores in between * All formatting rules specified in the selected sections of the Linux kernel Code Style for indentation, braces, spacing, etc * Header guards are formatted as '__LIBCAMERA_FILE_NAME_H__' Order of Includes ~~~~~~~~~~~~~~~~~ Headers shall be included at the beginning of .c, .cpp and .h files, right after the file description comment block and, for .h files, the header guard macro. For .cpp files, if the file implements an API declared in a header file, that header file shall be included first in order to ensure it is self-contained. The headers shall be grouped and ordered as follows: 1. The header declaring the API being implemented (if any) 2. The C and C++ system and standard library headers 3. Other libraries' headers, with one group per library 4. Other project's headers Groups of headers shall be separated by a single blank line. Headers within each group shall be sorted alphabetically. System and library headers shall be included with angle brackets. Project headers shall be included with angle brackets for the libcamera public API headers, and with double quotes for other libcamera headers. C++ Specific Rules ------------------ The code shall be implemented in C++14, with the following caveats: * Type inference (auto and decltype) shall be used with caution, to avoid drifting towards an untyped language. * The explicit, override and final specifiers are to be used where applicable. * General-purpose smart pointers (std::unique_ptr) deprecate std::auto_ptr. Smart pointers, as well as shared pointers and weak pointers, shall not be overused. * Classes are encouraged to define move constructors and assignment operators where applicable, and generally make use of the features offered by rvalue references. Object Ownership ~~~~~~~~~~~~~~~~ libcamera creates and destroys many objects at runtime, for both objects internal to the library and objects exposed to the user. To guarantee proper operation without use after free, double free or memory leaks, knowing who owns each object at any time is crucial. The project has enacted a set of rules to make object ownership tracking as explicit and fool-proof as possible. In the context of this section, the terms object and instance are used interchangeably and both refer to an instance of a class. The term reference refers to both C++ references and C++ pointers in their capacity to refer to an object. Passing a reference means offering a way to a callee to obtain a reference to an object that the caller has a valid reference to. Borrowing a reference means using a reference passed by a caller without ownership transfer based on the assumption that the caller guarantees the validity of the reference for the duration of the operation that borrows it. 1. Single Owner Objects * By default an object has a single owner at any time. * Storage of single owner objects varies depending on how the object ownership will evolve through the lifetime of the object. * Objects whose ownership needs to be transferred shall be stored as std::unique_ptr<> as much as possible to emphasize the single ownership. * Objects whose owner doesn't change may be embedded in other objects, or stored as pointer or references. They may be stored as std::unique_ptr<> for automatic deletion if desired. * Ownership is transferred by passing the reference as a std::unique_ptr<> and using std::move(). After ownership transfer the former owner has no valid reference to the object anymore and shall not access it without first obtaining a valid reference. * Objects may be borrowed by passing an object reference from the owner to the borrower, providing that * the owner guarantees the validity of the reference for the whole duration of the borrowing, and * the borrower doesn't access the reference after the end of the borrowing. When borrowing from caller to callee for the duration of a function call, this implies that the callee shall not keep any stored reference after it returns. These rules apply to the callee and all the functions it calls, directly or indirectly. When the object is stored in a std::unique_ptr<>, borrowing passes a reference to the object, not to the std::unique_ptr<>, as * a 'const &' when the object doesn't need to be modified and may not be null. * a pointer when the object may be modified or may be null. Unless otherwise specified, pointers passed to functions are considered as borrowed references valid for the duration of the function only. 2. Shared Objects * Objects that may have multiple owners at a given time are called shared objects. They are reference-counted and live as long as any references to the object exist. * Shared objects are created with std::make_shared<> or std::allocate_shared<> and stored in an std::shared_ptr<>. * Ownership is shared by creating and passing copies of any valid std::shared_ptr<>. Ownership is released by destroying the corresponding std::shared_ptr<>. * When passed to a function, std::shared_ptr<> are always passed by value, never by reference. The caller can decide whether to transfer its ownership of the std::shared_ptr<> with std::move() or retain it. The callee shall use std::move() if it needs to store the shared pointer. * Do not over-use std::move(), as it may prevent copy-elision. In particular a function returning a std::shared_ptr<> value shall not use std::move() in its return statements, and its callers shall not wrap the function call with std::move(). * Borrowed references to shared objects are passed as references to the objects themselves, not to the std::shared_ptr<>, with the same rules as for single owner objects. These rules match the `object ownership rules from the Chromium C++ Style Guide`_. .. _object ownership rules from the Chromium C++ Style Guide: https://chromium.googlesource.com/chromium/src/+/master/styleguide/c++/c++.md#object-ownership-and-calling-conventions .. attention:: Long term borrowing of single owner objects is allowed. Example use cases are implementation of the singleton pattern (where the singleton guarantees the validity of the reference forever), or returning references to global objects whose lifetime matches the lifetime of the application. As long term borrowing isn't marked through language constructs, it shall be documented explicitly in details in the API. C Compatibility Headers ~~~~~~~~~~~~~~~~~~~~~~~ The C++ standard defines a set of C++ standard library headers, and for some of them, defines C compatibility headers. The former have a name of the form while the later are named . The C++ headers declare names in the std namespace, and may declare the same names in the global namespace. The C compatibility headers declare names in the global namespace, and may declare the same names in the std namespace. Usage of the C compatibility headers is strongly preferred. Code shall not rely on the optional declaration of names in the global or std namespace. Documentation ------------- All public and protected classes, structures, enumerations, macros, functions and variables shall be documented with a Doxygen comment block, using the Javadoc style with C-style comments. When documenting private member functions and variables the same Doxygen style shall be used as for public and protected members. Documentation relates to header files, but shall be stored in the .cpp source files in order to group the implementation and documentation. Every documented header file shall have a \file documentation block in the .cpp source file. The following comment block shows an example of correct documentation for a member function of the PipelineHandler class. :: /** * \fn PipelineHandler::start() * \brief Start capturing from a group of streams * \param[in] camera The camera to start * * Start the group of streams that have been configured for capture by * \a configureStreams(). The intended caller of this method is the Camera * class which will in turn be called from the application to indicate that * it has configured the streams and is ready to capture. * * \return 0 on success or a negative error code otherwise */ The comment block shall be placed right before the function it documents. If the function is defined inline in the class definition in the header file, the comment block shall be placed alone in the .cpp source file in the same order as the function definitions in the header file and shall start with an \fn line. Otherwise no \fn line shall be present. The \brief directive shall be present. If the function takes parameters, \param directives shall be present, with the appropriate [in], [out] or [inout] specifiers. Only when the direction of the parameters isn't known (for instance when defining a template function with variadic arguments) the direction specifier shall be omitted. The \return directive shall be present when the function returns a value, and shall be omitted otherwise. The long description is optional. When present it shall be surrounded by empty lines and may span multiple paragraphs. No blank lines shall otherwise be added between the \fn, \brief, \param and \return directives. Tools ----- The 'clang-format' code formatting tool can be used to reformat source files with the libcamera coding style, defined in the .clang-format file at the root of the source tree. Alternatively the 'astyle' tool can also be used, with the following arguments. :: --style=linux --indent=force-tab=8 --attach-namespaces --attach-extern-c --pad-oper --align-pointer=name --align-reference=name --max-code-length=120 Use of astyle is discouraged as clang-format better matches the libcamera coding style. As both astyle and clang-format are code formatters, they operate on full files and output reformatted source code. While they can be used to reformat code before sending patches, it may generate unrelated changes. To avoid this, libcamera provides a 'checkstyle.py' script wrapping the formatting tools to only retain related changes. This should be used to validate modifications before submitting them for review. The script operates on one or multiple git commits specified on the command line. It does not modify the git tree, the index or the working directory and is thus safe to run at any point. Commits are specified using the same revision range syntax as 'git log'. The most usual use cases are to specify a single commit by sha1, branch name or tag name, or a commit range with the .. syntax. When no arguments are given, the topmost commit of the current branch is selected. :: $ ./utils/checkstyle.py cc7d204b2c51 ---------------------------------------------------------------------------------- cc7d204b2c51853f7d963d144f5944e209e7ea29 libcamera: Use the logger instead of cout ---------------------------------------------------------------------------------- No style issue detected When operating on a range of commits, style checks are performed on each commit from oldest to newest. :: $ ../utils/checkstyle.py 3b56ddaa96fb~3..3b56ddaa96fb ---------------------------------------------------------------------------------- b4351e1a6b83a9cfbfc331af3753602a02dbe062 libcamera: log: Fix Doxygen documentation ---------------------------------------------------------------------------------- No style issue detected -------------------------------------------------------------------------------------- 6ab3ff4501fcfa24db40fcccbce35bdded7cd4bc libcamera: log: Document the LogMessage class -------------------------------------------------------------------------------------- No style issue detected --------------------------------------------------------------------------------- 3b56ddaa96fbccf4eada05d378ddaa1cb6209b57 build: Add 'std=c++11' cpp compiler flag --------------------------------------------------------------------------------- Commit doesn't touch source files, skipping Commits that do not touch any .c, .cpp or .h files are skipped. :: $ ./utils/checkstyle.py edbd2059d8a4 ---------------------------------------------------------------------- edbd2059d8a4bd759302ada4368fa40556 /* * bcm2835-isp.h * * BCM2835 ISP driver - user space header file. * * Copyright © 2019-2020 Raspberry Pi Ltd * * Author: Naushir Patuck (naush@raspberrypi.com) * */ #ifndef __BCM2835_ISP_H_ #define __BCM2835_ISP_H_ #include <linux/v4l2-controls.h> #define V4L2_CID_USER_BCM2835_ISP_CC_MATRIX \ (V4L2_CID_USER_BCM2835_ISP_BASE + 0x0001) #define V4L2_CID_USER_BCM2835_ISP_LENS_SHADING \ (V4L2_CID_USER_BCM2835_ISP_BASE + 0x0002) #define V4L2_CID_USER_BCM2835_ISP_BLACK_LEVEL \ (V4L2_CID_USER_BCM2835_ISP_BASE + 0x0003) #define V4L2_CID_USER_BCM2835_ISP_GEQ \ (V4L2_CID_USER_BCM2835_ISP_BASE + 0x0004) #define V4L2_CID_USER_BCM2835_ISP_GAMMA \ (V4L2_CID_USER_BCM2835_ISP_BASE + 0x0005) #define V4L2_CID_USER_BCM2835_ISP_DENOISE \ (V4L2_CID_USER_BCM2835_ISP_BASE + 0x0006) #define V4L2_CID_USER_BCM2835_ISP_SHARPEN \ (V4L2_CID_USER_BCM2835_ISP_BASE + 0x0007) #define V4L2_CID_USER_BCM2835_ISP_DPC \ (V4L2_CID_USER_BCM2835_ISP_BASE + 0x0008) #define V4L2_CID_USER_BCM2835_ISP_CDN \ (V4L2_CID_USER_BCM2835_ISP_BASE + 0x0009) /* * All structs below are directly mapped onto the equivalent structs in * drivers/staging/vc04_services/vchiq-mmal/mmal-parameters.h * for convenience. */ /** * struct bcm2835_isp_rational - Rational value type. * * @num: Numerator. * @den: Denominator. */ struct bcm2835_isp_rational { __s32 num; __u32 den; }; /** * struct bcm2835_isp_ccm - Colour correction matrix. * * @ccm: 3x3 correction matrix coefficients. * @offsets: 1x3 correction offsets. */ struct bcm2835_isp_ccm { struct bcm2835_isp_rational ccm[3][3]; __s32 offsets[3]; }; /** * struct bcm2835_isp_custom_ccm - Custom CCM applied with the * V4L2_CID_USER_BCM2835_ISP_CC_MATRIX ctrl. * * @enabled: Enable custom CCM. * @ccm: Custom CCM coefficients and offsets. */ struct bcm2835_isp_custom_ccm { __u32 enabled; struct bcm2835_isp_ccm ccm; }; /** * enum bcm2835_isp_gain_format - format of the gains in the lens shading * tables used with the * V4L2_CID_USER_BCM2835_ISP_LENS_SHADING ctrl. * * @GAIN_FORMAT_U0P8_1: Gains are u0.8 format, starting at 1.0 * @GAIN_FORMAT_U1P7_0: Gains are u1.7 format, starting at 0.0 * @GAIN_FORMAT_U1P7_1: Gains are u1.7 format, starting at 1.0 * @GAIN_FORMAT_U2P6_0: Gains are u2.6 format, starting at 0.0 * @GAIN_FORMAT_U2P6_1: Gains are u2.6 format, starting at 1.0 * @GAIN_FORMAT_U3P5_0: Gains are u3.5 format, starting at 0.0 * @GAIN_FORMAT_U3P5_1: Gains are u3.5 format, starting at 1.0 * @GAIN_FORMAT_U4P10: Gains are u4.10 format, starting at 0.0 */ enum bcm2835_isp_gain_format { GAIN_FORMAT_U0P8_1 = 0, GAIN_FORMAT_U1P7_0 = 1, GAIN_FORMAT_U1P7_1 = 2, GAIN_FORMAT_U2P6_0 = 3, GAIN_FORMAT_U2P6_1 = 4, GAIN_FORMAT_U3P5_0 = 5, GAIN_FORMAT_U3P5_1 = 6, GAIN_FORMAT_U4P10 = 7, }; /** * struct bcm2835_isp_lens_shading - Lens shading tables supplied with the * V4L2_CID_USER_BCM2835_ISP_LENS_SHADING * ctrl. * * @enabled: Enable lens shading. * @grid_cell_size: Size of grid cells in samples (16, 32, 64, 128 or 256). * @grid_width: Width of lens shading tables in grid cells. * @grid_stride: Row to row distance (in grid cells) between grid cells * in the same horizontal location. * @grid_height: Height of lens shading tables in grid cells. * @dmabuf: dmabuf file handle containing the table. * @ref_transform: Reference transform - unsupported, please pass zero. * @corner_sampled: Whether the gains are sampled at the corner points * of the grid cells or in the cell centres. * @gain_format: Format of the gains (see enum &bcm2835_isp_gain_format). */ struct bcm2835_isp_lens_shading { __u32 enabled; __u32 grid_cell_size; __u32 grid_width; __u32 grid_stride; __u32 grid_height; __s32 dmabuf; __u32 ref_transform; __u32 corner_sampled; __u32 gain_format; }; /** * struct bcm2835_isp_black_level - Sensor black level set with the * V4L2_CID_USER_BCM2835_ISP_BLACK_LEVEL ctrl. * * @enabled: Enable black level. * @black_level_r: Black level for red channel. * @black_level_g: Black level for green channels. * @black_level_b: Black level for blue channel. */ struct bcm2835_isp_black_level { __u32 enabled; __u16 black_level_r; __u16 black_level_g; __u16 black_level_b; __u8 padding[2]; /* Unused */ }; /** * struct bcm2835_isp_geq - Green equalisation parameters set with the * V4L2_CID_USER_BCM2835_ISP_GEQ ctrl. * * @enabled: Enable green equalisation. * @offset: Fixed offset of the green equalisation threshold. * @slope: Slope of the green equalisation threshold. */ struct bcm2835_isp_geq { __u32 enabled; __u32 offset; struct bcm2835_isp_rational slope; }; #define BCM2835_NUM_GAMMA_PTS 33 /** * struct bcm2835_isp_gamma - Gamma parameters set with the * V4L2_CID_USER_BCM2835_ISP_GAMMA ctrl. * * @enabled: Enable gamma adjustment. * @X: X values of the points defining the gamma curve. * Values should be scaled to 16 bits. * @Y: Y values of the points defining the gamma curve. * Values should be scaled to 16 bits. */ struct bcm2835_isp_gamma { __u32 enabled; __u16 x[BCM2835_NUM_GAMMA_PTS]; __u16 y[BCM2835_NUM_GAMMA_PTS]; }; /** * enum bcm2835_isp_cdn_mode - Mode of operation for colour denoise. * * @CDN_MODE_FAST: Fast (but lower quality) colour denoise * algorithm, typically used for video recording. * @CDN_HIGH_QUALITY: High quality (but slower) colour denoise * algorithm, typically used for stills capture. */ enum bcm2835_isp_cdn_mode { CDN_MODE_FAST = 0, CDN_MODE_HIGH_QUALITY = 1, }; /** * struct bcm2835_isp_cdn - Colour denoise parameters set with the * V4L2_CID_USER_BCM2835_ISP_CDN ctrl. * * @enabled: Enable colour denoise. * @cdn_mode: Colour denoise operating mode (see enum &bcm2835_isp_cdn_mode) */ struct bcm2835_isp_cdn { __u32 enabled; __u32 mode; }; /** * struct bcm2835_isp_denoise - Denoise parameters set with the * V4L2_CID_USER_BCM2835_ISP_DENOISE ctrl. * * @enabled: Enable denoise. * @constant: Fixed offset of the noise threshold. * @slope: Slope of the noise threshold. * @strength: Denoise strength between 0.0 (off) and 1.0 (maximum). */ struct bcm2835_isp_denoise { __u32 enabled; __u32 constant; struct bcm2835_isp_rational slope; struct bcm2835_isp_rational strength; }; /** * struct bcm2835_isp_sharpen - Sharpen parameters set with the * V4L2_CID_USER_BCM2835_ISP_SHARPEN ctrl. * * @enabled: Enable sharpening. * @threshold: Threshold at which to start sharpening pixels. * @strength: Strength with which pixel sharpening increases. * @limit: Limit to the amount of sharpening applied. */ struct bcm2835_isp_sharpen { __u32 enabled; struct bcm2835_isp_rational threshold; struct bcm2835_isp_rational strength; struct bcm2835_isp_rational limit; }; /** * enum bcm2835_isp_dpc_mode - defective pixel correction (DPC) strength. * * @DPC_MODE_OFF: No DPC. * @DPC_MODE_NORMAL: Normal DPC. * @DPC_MODE_STRONG: Strong DPC. */ enum bcm2835_isp_dpc_mode { DPC_MODE_OFF = 0, DPC_MODE_NORMAL = 1, DPC_MODE_STRONG = 2, }; /** * struct bcm2835_isp_dpc - Defective pixel correction (DPC) parameters set * with the V4L2_CID_USER_BCM2835_ISP_DPC ctrl. * * @enabled: Enable DPC. * @strength: DPC strength (see enum &bcm2835_isp_dpc_mode). */ struct bcm2835_isp_dpc { __u32 enabled; __u32 strength; }; /* * ISP statistics structures. * * The bcm2835_isp_stats structure is generated at the output of the * statistics node. Note that this does not directly map onto the statistics * output of the ISP HW. Instead, the MMAL firmware code maps the HW statistics * to the bcm2835_isp_stats structure. */ #define DEFAULT_AWB_REGIONS_X 16 #define DEFAULT_AWB_REGIONS_Y 12 #define NUM_HISTOGRAMS 2 #define NUM_HISTOGRAM_BINS 128 #define AWB_REGIONS (DEFAULT_AWB_REGIONS_X * DEFAULT_AWB_REGIONS_Y) #define FLOATING_REGIONS 16 #define AGC_REGIONS 16 #define FOCUS_REGIONS 12 /** * struct bcm2835_isp_stats_hist - Histogram statistics * * @r_hist: Red channel histogram. * @g_hist: Combined green channel histogram. * @b_hist: Blue channel histogram. */ struct bcm2835_isp_stats_hist { __u32 r_hist[NUM_HISTOGRAM_BINS]; __u32 g_hist[NUM_HISTOGRAM_BINS]; __u32 b_hist[NUM_HISTOGRAM_BINS]; }; /** * struct bcm2835_isp_stats_region - Region sums. * * @counted: The number of 2x2 bayer tiles accumulated. * @notcounted: The number of 2x2 bayer tiles not accumulated. * @r_sum: Total sum of counted pixels in the red channel for a region. * @g_sum: Total sum of counted pixels in the green channel for a region. * @b_sum: Total sum of counted pixels in the blue channel for a region. */ struct bcm2835_isp_stats_region { __u32 counted; __u32 notcounted; __u64 r_sum; __u64 g_sum; __u64 b_sum; }; /** * struct bcm2835_isp_stats_focus - Focus statistics. * * @contrast_val: Focus measure - accumulated output of the focus filter. * In the first dimension, index [0] counts pixels below a * preset threshold, and index [1] counts pixels above the * threshold. In the second dimension, index [0] uses the * first predefined filter, and index [1] uses the second * predefined filter. * @contrast_val_num: The number of counted pixels in the above accumulation. */ struct bcm2835_isp_stats_focus { __u64 contrast_val[2][2]; __u32 contrast_val_num[2][2]; }; /** * struct bcm2835_isp_stats - ISP statistics. * * @version: Version of the bcm2835_isp_stats structure. * @size: Size of the bcm2835_isp_stats structure. * @hist: Histogram statistics for the entire image. * @awb_stats: Statistics for the regions defined for AWB calculations. * @floating_stats: Statistics for arbitrarily placed (floating) regions. * @agc_stats: Statistics for the regions defined for AGC calculations. * @focus_stats: Focus filter statistics for the focus regions. */ struct bcm2835_isp_stats { __u32 version; __u32 size; struct bcm2835_isp_stats_hist hist[NUM_HISTOGRAMS]; struct bcm2835_isp_stats_region awb_stats[AWB_REGIONS]; struct bcm2835_isp_stats_region floating_stats[FLOATING_REGIONS]; struct bcm2835_isp_stats_region agc_stats[AGC_REGIONS]; struct bcm2835_isp_stats_focus focus_stats[FOCUS_REGIONS]; }; #endif /* __BCM2835_ISP_H_ */
generated by cgit v1.2.1 (git 2.18.0) at 2025-01-04 14:03:40 +0000