~hc/RK356X_SDK_RELEASE.git

..	..	@@ -56,7 +56,7 @@
56	56	case 'K':
57	57	case 'k':
58	58	mem <<= 10;
59		- /* fall through */
	59	+ fallthrough;
60	60	default:
61	61	break;
62	62	}
..	..	@@ -84,15 +84,20 @@
84	84	Coding style is all about readability and maintainability using commonly
85	85	available tools.
86	86
87		-The limit on the length of lines is 80 columns and this is a strongly
88		-preferred limit.
	87	+The preferred limit on the length of a single line is 80 columns.
89	88
90		-Statements longer than 80 columns will be broken into sensible chunks, unless
91		-exceeding 80 columns significantly increases readability and does not hide
92		-information. Descendants are always substantially shorter than the parent and
93		-are placed substantially to the right. The same applies to function headers
94		-with a long argument list. However, never break user-visible strings such as
95		-printk messages, because that breaks the ability to grep for them.
	89	+Statements longer than 80 columns should be broken into sensible chunks,
	90	+unless exceeding 80 columns significantly increases readability and does
	91	+not hide information.
	92	+
	93	+Descendants are always substantially shorter than the parent and
	94	+are placed substantially to the right. A very commonly used style
	95	+is to align descendants to a function open parenthesis.
	96	+
	97	+These same rules are applied to function headers with a long argument list.
	98	+
	99	+However, never break user-visible strings such as printk messages because
	100	+that breaks the ability to grep for them.
96	101
97	102
98	103	3) Placing Braces and Spaces
..	..	@@ -284,9 +289,9 @@
284	289	4) Naming
285	290	---------
286	291
287		-C is a Spartan language, and so should your naming be. Unlike Modula-2
288		-and Pascal programmers, C programmers do not use cute names like
289		-ThisVariableIsATemporaryCounter. A C programmer would call that
	292	+C is a Spartan language, and your naming conventions should follow suit.
	293	+Unlike Modula-2 and Pascal programmers, C programmers do not use cute
	294	+names like ThisVariableIsATemporaryCounter. A C programmer would call that
290	295	variable ``tmp``, which is much easier to write, and not the least more
291	296	difficult to understand.
292	297
..	..	@@ -300,9 +305,9 @@
300	305	``count_active_users()`` or similar, you should not call it ``cntusr()``.
301	306
302	307	Encoding the type of a function into the name (so-called Hungarian
303		-notation) is brain damaged - the compiler knows the types anyway and can
304		-check those, and it only confuses the programmer. No wonder MicroSoft
305		-makes buggy programs.
	308	+notation) is asinine - the compiler knows the types anyway and can check
	309	+those, and it only confuses the programmer. No wonder Microsoft makes buggy
	310	+programs.
306	311
307	312	LOCAL variable names should be short, and to the point. If you have
308	313	some random integer loop counter, it should probably be called ``i``.
..	..	@@ -314,6 +319,26 @@
314	319	problem, which is called the function-growth-hormone-imbalance syndrome.
315	320	See chapter 6 (Functions).
316	321
	322	+For symbol names and documentation, avoid introducing new usage of
	323	+'master / slave' (or 'slave' independent of 'master') and 'blacklist /
	324	+whitelist'.
	325	+
	326	+Recommended replacements for 'master / slave' are:
	327	+ '{primary,main} / {secondary,replica,subordinate}'
	328	+ '{initiator,requester} / {target,responder}'
	329	+ '{controller,host} / {device,worker,proxy}'
	330	+ 'leader / follower'
	331	+ 'director / performer'
	332	+
	333	+Recommended replacements for 'blacklist/whitelist' are:
	334	+ 'denylist / allowlist'
	335	+ 'blocklist / passlist'
	336	+
	337	+Exceptions for introducing new usage is to maintain a userspace ABI/API,
	338	+or when updating code for an existing (as of 2020) hardware or protocol
	339	+specification that mandates those terms. For new specifications
	340	+translate specification usage of the terminology to the kernel coding
	341	+standard where possible.
317	342
318	343	5) Typedefs
319	344	-----------
..	..	@@ -442,6 +467,9 @@
442	467	In function prototypes, include parameter names with their data types.
443	468	Although this is not required by the C language, it is preferred in Linux
444	469	because it is a simple way to add valuable information for the reader.
	470	+
	471	+Do not use the ``extern`` keyword with function prototypes as this makes
	472	+lines longer and isn't strictly necessary.
445	473
446	474
447	475	7) Centralized exiting of functions
..	..	@@ -592,26 +620,43 @@
592	620	(* (max steps 1)
593	621	c-basic-offset)))
594	622
595		- (add-hook 'c-mode-common-hook
596		- (lambda ()
597		- ;; Add kernel style
598		- (c-add-style
599		- "linux-tabs-only"
600		- '("linux" (c-offsets-alist
601		- (arglist-cont-nonempty
602		- c-lineup-gcc-asm-reg
603		- c-lineup-arglist-tabs-only))))))
	623	+ (dir-locals-set-class-variables
	624	+ 'linux-kernel
	625	+ '((c-mode . (
	626	+ (c-basic-offset . 8)
	627	+ (c-label-minimum-indentation . 0)
	628	+ (c-offsets-alist . (
	629	+ (arglist-close . c-lineup-arglist-tabs-only)
	630	+ (arglist-cont-nonempty .
	631	+ (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only))
	632	+ (arglist-intro . +)
	633	+ (brace-list-intro . +)
	634	+ (c . c-lineup-C-comments)
	635	+ (case-label . 0)
	636	+ (comment-intro . c-lineup-comment)
	637	+ (cpp-define-intro . +)
	638	+ (cpp-macro . -1000)
	639	+ (cpp-macro-cont . +)
	640	+ (defun-block-intro . +)
	641	+ (else-clause . 0)
	642	+ (func-decl-cont . +)
	643	+ (inclass . +)
	644	+ (inher-cont . c-lineup-multi-inher)
	645	+ (knr-argdecl-intro . 0)
	646	+ (label . -1000)
	647	+ (statement . 0)
	648	+ (statement-block-intro . +)
	649	+ (statement-case-intro . +)
	650	+ (statement-cont . +)
	651	+ (substatement . +)
	652	+ ))
	653	+ (indent-tabs-mode . t)
	654	+ (show-trailing-whitespace . t)
	655	+ ))))
604	656
605		- (add-hook 'c-mode-hook
606		- (lambda ()
607		- (let ((filename (buffer-file-name)))
608		- ;; Enable kernel mode for the appropriate files
609		- (when (and filename
610		- (string-match (expand-file-name "~/src/linux-trees")
611		- filename))
612		- (setq indent-tabs-mode t)
613		- (setq show-trailing-whitespace t)
614		- (c-set-style "linux-tabs-only")))))
	657	+ (dir-locals-set-directory-class
	658	+ (expand-file-name "~/src/linux-trees")
	659	+ 'linux-kernel)
615	660
616	661	This will make emacs go better with the kernel coding style for C
617	662	files below ``~/src/linux-trees``.
..	..	@@ -666,7 +711,7 @@
666	711	...
667	712
668	713	For full documentation on the configuration files, see the file
669		-Documentation/kbuild/kconfig-language.txt.
	714	+Documentation/kbuild/kconfig-language.rst.
670	715
671	716
672	717	11) Data structures
..	..	@@ -786,9 +831,9 @@
786	831	----------------------------
787	832
788	833	Kernel developers like to be seen as literate. Do mind the spelling
789		-of kernel messages to make a good impression. Do not use crippled
790		-words like ``dont``; use ``do not`` or ``don't`` instead. Make the messages
791		-concise, clear, and unambiguous.
	834	+of kernel messages to make a good impression. Do not use incorrect
	835	+contractions like ``dont``; use ``do not`` or ``don't`` instead. Make the
	836	+messages concise, clear, and unambiguous.
792	837
793	838	Kernel messages do not have to be terminated with a period.
794	839
..	..	@@ -823,7 +868,8 @@
823	868	The kernel provides the following general purpose memory allocators:
824	869	kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and
825	870	vzalloc(). Please refer to the API documentation for further information
826		-about them.
	871	+about them. :ref:`Documentation/core-api/memory-allocation.rst
	872	+<memory_allocation>`
827	873
828	874	The preferred form for passing a size of a struct is the following:
829	875
..	..	@@ -854,6 +900,9 @@
854	900	Both forms check for overflow on the allocation size n * sizeof(...),
855	901	and return NULL if that occurred.
856	902
	903	+These generic allocation functions all emit a stack dump on failure when used
	904	+without __GFP_NOWARN so there is no use in emitting an additional failure
	905	+message when NULL is returned.
857	906
858	907	15) The inline disease
859	908	----------------------
..	..	@@ -918,7 +967,37 @@
918	967	NULL or the ERR_PTR mechanism to report failure.
919	968
920	969
921		-17) Don't re-invent the kernel macros
	970	+17) Using bool
	971	+--------------
	972	+
	973	+The Linux kernel bool type is an alias for the C99 _Bool type. bool values can
	974	+only evaluate to 0 or 1, and implicit or explicit conversion to bool
	975	+automatically converts the value to true or false. When using bool types the
	976	+!! construction is not needed, which eliminates a class of bugs.
	977	+
	978	+When working with bool values the true and false definitions should be used
	979	+instead of 1 and 0.
	980	+
	981	+bool function return types and stack variables are always fine to use whenever
	982	+appropriate. Use of bool is encouraged to improve readability and is often a
	983	+better option than 'int' for storing boolean values.
	984	+
	985	+Do not use bool if cache line layout or size of the value matters, as its size
	986	+and alignment varies based on the compiled architecture. Structures that are
	987	+optimized for alignment and size should not use bool.
	988	+
	989	+If a structure has many true/false values, consider consolidating them into a
	990	+bitfield with 1 bit members, or using an appropriate fixed width type, such as
	991	+u8.
	992	+
	993	+Similarly for function arguments, many true/false values can be consolidated
	994	+into a single bitwise 'flags' argument and 'flags' can often be a more
	995	+readable alternative if the call-sites have naked true/false constants.
	996	+
	997	+Otherwise limited use of bool in structures and arguments can improve
	998	+readability.
	999	+
	1000	+18) Don't re-invent the kernel macros
922	1001	-------------------------------------
923	1002
924	1003	The header file include/linux/kernel.h contains a number of macros that
..	..	@@ -934,14 +1013,14 @@
934	1013
935	1014	.. code-block:: c
936	1015
937		- #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f))
	1016	+ #define sizeof_field(t, f) (sizeof(((t*)0)->f))
938	1017
939	1018	There are also min() and max() macros that do strict type checking if you
940	1019	need them. Feel free to peruse that header file to see what else is already
941	1020	defined that you shouldn't reproduce in your code.
942	1021
943	1022
944		-18) Editor modelines and other cruft
	1023	+19) Editor modelines and other cruft
945	1024	------------------------------------
946	1025
947	1026	Some editors can interpret configuration information embedded in source files,
..	..	@@ -975,7 +1054,7 @@
975	1054	work correctly.
976	1055
977	1056
978		-19) Inline assembly
	1057	+20) Inline assembly
979	1058	-------------------
980	1059
981	1060	In architecture-specific code, you may need to use inline assembly to interface
..	..	@@ -1007,7 +1086,7 @@
1007	1086	: /* outputs / : / inputs / : / clobbers */);
1008	1087
1009	1088
1010		-20) Conditional Compilation
	1089	+21) Conditional Compilation
1011	1090	---------------------------
1012	1091
1013	1092	Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c
..	..	@@ -1070,10 +1149,10 @@
1070	1149	ISBN 0-201-61586-X.
1071	1150
1072	1151	GNU manuals - where in compliance with K&R and this text - for cpp, gcc,
1073		-gcc internals and indent, all available from http://www.gnu.org/manual/
	1152	+gcc internals and indent, all available from https://www.gnu.org/manual/
1074	1153
1075	1154	WG14 is the international standardization working group for the programming
1076	1155	language C, URL: http://www.open-std.org/JTC1/SC22/WG14/
1077	1156
1078		-Kernel process/coding-style.rst, by greg@kroah.com at OLS 2002:
	1157	+Kernel :ref:`process/coding-style.rst <codingstyle>`, by greg@kroah.com at OLS 2002:
1079	1158	http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/