iLLD_TC27xC  1.0
lld_dosanddont_enumUsage.c
Go to the documentation of this file.
1 /*
2 * $Author: $tklose
3 * $Date: 2014-02-26 09:24:12 GMT$
4 * $Revision: $0.2
5 */
6 /**
7 
8 \page lld_dosanddont_enumUsage Usage of enums
9  \section convention_in_std enum convention in microcontroller /Std drivers
10  <SPAN style="font-family:courier;font-size:small;">[link: \ref convention_in_std]</SPAN>
11 
12 
13  \todo Discuss and agree on the enum naming convention
14 
15  In case an enum represents a register bitfield value, then the following rules apply:
16  - The enum type shall have an explicit name. The name shall not include register or bitfield short names. This is to abstract the setting when passed as a parameter to a function in the same way the function APIs names does.
17  - Each enum member shall define explicitly an enum value with '='.
18  - The enum documentation shall state for which register bitfield the enum has been defined with "Definition for <ModuleType>.<REGISTER NAME>.B.<BITFIELDNAME>", this to avoid misuse of the enum.
19  - Each of the member shall have a documentation, that explain to users what is the enum for without reading the user manual.
20  - Only enum defined in the current Std or base drivers shall be used.
21 
22  Correct:
23  \code
24  // File Std/IfxQspi.h
25 
26  // QSPI controller mode
27  // Definition for Ifx_QSPI.GLOBALCON.B.MS
28  typedef enum
29  {
30  IfxQspi_Mode_master = 0, // QSPI in "master" mode
31  IfxQspi_Mode_pwmOverSpi = 1, // QSPI in "PWM over SPI" mode
32  IfxQspi_Mode_slave = 2 // QSPI in "slave" mode
33  } IfxQspi_Mode;
34 
35  void IfxQspi_foo(IfxQSPI* module)
36  {
37  if (module->GLOBALCON.B.MS != IfxQspi_Mode_slave)
38  { //...
39  }
40  else
41  { // ...
42  }
43  }
44 
45  \endcode
46 
47  Wrong:
48  \code
49  // File 1_SrvSw/If/SscIf.h
50 
51  // SSC operation modes
52  typedef enum
53  {
54  SscIf_Mode_master, // Master mode
55  SscIf_Mode_slave, // Slave mode
56  SscIf_Mode_undefined // Undefined mode
57  } SscIf_Mode;
58 
59  // File Std/IfxQspi.h
60 
61  // QSPI controller mode
62  typedef enum
63  {
64  IfxQspi_GLOBALCON_MS_master = 0, // Corresponds with GLOBALCON.B.MS == 0
65  IfxQspi_GLOBALCON_MS_pwmOverSpi, // Corresponds with GLOBALCON.B.MS == 1
66  IfxQspi_GLOBALCON_MS_slave // Corresponds with GLOBALCON.B.MS == 2
67  } IfxQspi_GLOBALCON_MS;
68 
69  void IfxQspi_foo(IfxQSPI* module)
70  {
71  if (module->GLOBALCON.B.MS != SscIf_Mode_slave)
72  { //...
73  }
74  else
75  { // ...
76  }
77  }
78 
79  \endcode
80 
81 
82  \section enum_in_std Usage of enums in microcontroller interface drivers
83  <SPAN style="font-family:courier;font-size:small;">[link: \ref enum_in_std]</SPAN>
84 
85 
86  The code dependencies shall be limited to the microcontroller HAL and service software interface /1_SrvSw/If, therefore only enums from this files can be used.
87 
88  \code
89  // File 1_SrvSw/If/SscIf.h
90 
91  // SSC operation modes
92  typedef enum
93  {
94  SscIf_Mode_master, // Master mode
95  SscIf_Mode_slave, // Slave mode
96  SscIf_Mode_undefined // Undefined mode
97  } SscIf_Mode;
98 
99  // File Ssc/IfxQspi_Ssc.h
100 
101  // QSPI controller mode
102  // Definition for Ifx_QSPI.GLOBALCON.B.MS
103  typedef enum
104  {
105  IfxQspi_Mode_master = 0, // QSPI in "master" mode
106  IfxQspi_Mode_pwmOverSpi = 1, // QSPI in "PWM over SPI" mode
107  IfxQspi_Mode_slave = 2 // QSPI in "slave" mode
108  } IfxQspi_Mode;
109 
110  ...
111 
112  SscIf_Mode IfxQspi_Ssc_foo(void)
113  {
114  SscIf_Mode mode;
115  switch ( IfxQspi_getMode(&MODULE_QSPI0))
116  {
117  case IfxQspi_Mode_master:
118  mode = SscIf_Mode_master;
119  break;
120  case IfxQspi_Mode_slave:
121  mode = IfxQspi_Mode_slave;
122  break;
123  default:
124  mode = SscIf_Mode_undefined;
125  break;
126  }
127  }
128  \endcode
129 
130  \section enumIndex Enum name with index
131  <SPAN style="font-family:courier;font-size:small;">[link: \ref enumIndex]</SPAN>
132 
133  Do not use left zero padding for enum names, because the highest index number can not be assumed to be fixed.
134 
135  Correct:
136  \code
137  typedef enum
138  {
139  Dma_Channel_0 = 0,
140  Dma_Channel_1 = 1,
141  Dma_Channel_2 = 2,
142  Dma_Channel_3 = 3
143  } IfxQspi_Mode;
144  \endcode
145 
146  Wrong:
147  \code
148  typedef enum
149  {
150  Dma_Channel_00 = 0,
151  Dma_Channel_01 = 1,
152  Dma_Channel_02 = 2,
153  Dma_Channel_03 = 3
154  } IfxQspi_Mode;
155  \endcode
156 
157  \section enumPrefix 14. Enum members shall be prefixed with the enum type
158  <SPAN style="font-family:courier;font-size:small;">[link: \ref enumPrefix]</SPAN>
159 
160 
161  Correct:
162  \code
163  typedef enum
164  {
165  IfxDma_Channel_0 = 0,
166  } IfxDma_Channel;
167  \endcode
168 
169  Wrong(<SPAN style="font-family:courier">IfxDma_Channel<SPAN style="color:red">Id</SPAN></SPAN>):
170  \code
171  typedef enum
172  {
173  Dma_Channel_0 = 0,
174  } IfxDma_ChannelId;
175  \endcode
176 
177 
178 
179 
180 [\ref lld_dosanddont_optimisation "Previous page"]
181 
182 
183 
184  */