Skip to content

Commit 7de365c

Browse files
wdx04wdx04
committed
added basic documentation for CAN HAL API functions
removed the unused parameter 'cc' from can_write and canfd_write reverted changes in TARGET_STM/sleep.c
1 parent 02e2c35 commit 7de365c

File tree

16 files changed

+262
-128
lines changed

16 files changed

+262
-128
lines changed

‎drivers/source/CAN.cpp‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@ int CAN::frequency(int f, int data_f)
8989
int CAN::write(CANMessage msg)
9090
{
9191
lock();
92-
int ret = can_write(&_can, msg, 0);
92+
int ret = can_write(&_can, msg);
9393
unlock();
9494
return ret;
9595
}
@@ -110,7 +110,7 @@ int CAN::read(CANMessage &msg, int handle)
110110
int CAN::write(CANFDMessage msg)
111111
{
112112
lock();
113-
int ret = canfd_write(&_can, msg, 0);
113+
int ret = canfd_write(&_can, msg);
114114
unlock();
115115
return ret;
116116
}

‎hal/include/hal/can_api.h‎

Lines changed: 171 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -67,31 +67,200 @@ typedef void (*can_irq_handler)(uintptr_t context, CanIrqType type);
6767

6868
typedef struct can_s can_t;
6969

70+
/** Initialize the CAN peripheral. It sets the default parameters for CAN
71+
* peripheral, and configures its specifieds pins.
72+
*
73+
* @param obj CAN object
74+
* @param rd The CAN RD pin name
75+
* @param td The CAN TD pin name
76+
*/
7077
void can_init(can_t *obj, PinName rd, PinName td);
78+
79+
/** Initialize the CAN peripheral. It sets the default parameters for CAN
80+
* peripheral, and configures its specifieds pins.
81+
*
82+
* @param obj The CAN object
83+
* @param pinmap pointer to structure which holds static pinmap
84+
*/
7185
void can_init_direct(can_t *obj, const can_pinmap_t *pinmap);
86+
87+
/** Initialize the CAN peripheral. It sets the default parameters for CAN
88+
* peripheral, and configures its specifieds pins.
89+
*
90+
* @param obj CAN object
91+
* @param rd The CAN RD pin name
92+
* @param td The CAN TD pin name
93+
* @param hz The bus frequency
94+
*/
7295
void can_init_freq(can_t *obj, PinName rd, PinName td, int hz);
96+
97+
/** Initialize the CAN peripheral. It sets the default parameters for CAN
98+
* peripheral, and configures its specifieds pins.
99+
*
100+
* @param obj CAN object
101+
* @param pinmap pointer to structure which holds static pinmap
102+
* @param hz The bus frequency
103+
*/
73104
void can_init_freq_direct(can_t *obj, const can_pinmap_t *pinmap, int hz);
105+
106+
/** Release the CAN peripheral, not currently invoked. It requires further
107+
* resource management.
108+
*
109+
* @param obj The CAN object
110+
*/
74111
void can_free(can_t *obj);
112+
113+
/** Configure the CAN bus frequency
114+
*
115+
* @param obj The CAN object
116+
* @param hz The bus frequency
117+
*/
75118
int can_frequency(can_t *obj, int hz);
76119

120+
/** Initialize the CAN IRQ handler
121+
*
122+
* @param obj The CAN object
123+
* @param handler The handler to be attached to CAN IRQ
124+
* @param context The context to be passed back to the handler (context != 0, 0 is reserved)
125+
*/
77126
void can_irq_init(can_t *obj, can_irq_handler handler, uintptr_t context);
127+
128+
/** Release the CAN object
129+
*
130+
* @param obj The CAN object
131+
*/
78132
void can_irq_free(can_t *obj);
133+
134+
/** Enable/disable the CAN IRQ event
135+
*
136+
* @param obj The CAN object
137+
* @param irq The CAN IRQ event
138+
* @param enable The enable flag
139+
*/
79140
void can_irq_set(can_t *obj, CanIrqType irq, uint32_t enable);
80141

81-
int can_write(can_t *obj, CAN_Message, int cc);
142+
/** Write a CAN message to the bus.
143+
*
144+
* @param obj The CAN object
145+
* @param msg The CAN message to write.
146+
*
147+
* @return 0 if write failed,
148+
* 1 if write was successful
149+
*/
150+
int can_write(can_t *obj, CAN_Message msg);
151+
152+
/** Read a CAN message from the bus.
153+
*
154+
* @param obj CAN object
155+
* @param msg A CAN message to read to.
156+
* @param handle message filter handle (0 for any message).
157+
*
158+
* @return 0 if no message arrived,
159+
* 1 if message arrived
160+
*/
82161
int can_read(can_t *obj, CAN_Message *msg, int handle);
162+
163+
/** Change CAN operation to the specified mode.
164+
*
165+
* @param obj The CAN object
166+
* @param mode The new operation mode (MODE_NORMAL, MODE_SILENT, MODE_TEST_LOCAL, MODE_TEST_GLOBAL, MODE_TEST_SILENT).
167+
*
168+
* @return 0 if mode change failed or unsupported,
169+
* 1 if mode change was successful
170+
*/
83171
int can_mode(can_t *obj, CanMode mode);
172+
173+
/** Filter out incomming messages.
174+
*
175+
* @param obj The CAN object
176+
* @param id the id to filter on.
177+
* @param mask the mask applied to the id.
178+
* @param format format to filter on (Default CANAny).
179+
* @param handle message filter handle (Optional).
180+
*
181+
* @return 0 if filter change failed or unsupported,
182+
* new filter handle if successful
183+
*/
84184
int can_filter(can_t *obj, uint32_t id, uint32_t mask, CANFormat format, int32_t handle);
185+
186+
/** Reset CAN interface.
187+
*
188+
* @param obj CAN object
189+
*
190+
* To use after error overflow.
191+
*/
85192
void can_reset(can_t *obj);
193+
194+
/** Detects read errors - Used to detect read overflow errors.
195+
*
196+
* @param obj CAN object
197+
* @return number of read errors
198+
*/
86199
unsigned char can_rderror(can_t *obj);
200+
201+
/** Detects write errors - Used to detect write overflow errors.
202+
*
203+
* @param obj CAN object
204+
* @return number of write errors
205+
*/
87206
unsigned char can_tderror(can_t *obj);
207+
208+
/** Puts or removes the CAN interface into silent monitoring mode.
209+
*
210+
* @param obj CAN object
211+
* @param silent boolean indicating whether to go into silent mode or not.
212+
*/
88213
void can_monitor(can_t *obj, int silent);
89214

90215
#if DEVICE_CAN_FD
216+
/** Initialize the CAN FD peripheral. It sets the default parameters for CAN FD
217+
* peripheral, and configures its specifieds pins.
218+
*
219+
* @param obj CAN object
220+
* @param rd The CAN RD pin name
221+
* @param td The CAN TD pin name
222+
* @param hz The bus frequency of nominal phase
223+
* @param data_hz The bus frequency of data phase, the CAN object is put into Classical CAN mode if this parameter is zero
224+
*/
91225
void canfd_init_freq(can_t *obj, PinName rd, PinName td, int hz, int data_hz);
226+
227+
/** Initialize the CAN FD peripheral. It sets the default parameters for CAN FD
228+
* peripheral, and configures its specifieds pins.
229+
*
230+
* @param obj CAN object
231+
* @param pinmap pointer to structure which holds static pinmap
232+
* @param hz The bus frequency of nominal phase
233+
* @param data_hz The bus frequency of data phase, the CAN object is put into Classical CAN mode if this parameter is zero
234+
*/
92235
void canfd_init_freq_direct(can_t *obj, const can_pinmap_t *pinmap, int hz, int data_hz);
236+
237+
/** Configure the CAN FD bus frequency
238+
*
239+
* @param obj The CAN object
240+
* @param hz The bus frequency of nominal phase
241+
* @param data_hz The bus frequency of data phase, the CAN object is put into Classical CAN mode if this parameter is zero
242+
*/
93243
int canfd_frequency(can_t *obj, int hz, int data_hz);
94-
int canfd_write(can_t *obj, CANFD_Message, int cc);
244+
245+
/** Write a CAN FD Message to the bus.
246+
*
247+
* @param obj The CAN object
248+
* @param msg The CAN FD Message to write.
249+
*
250+
* @return 0 if write failed,
251+
* 1 if write was successful
252+
*/
253+
int canfd_write(can_t *obj, CANFD_Message msg);
254+
255+
/** Read a Classical CAN or CAN FD Message from the bus.
256+
*
257+
* @param obj CAN object
258+
* @param msg A Classical CAN or CAN FD Message to read to.
259+
* @param handle message filter handle (0 for any message).
260+
*
261+
* @return 0 if no message arrived,
262+
* 1 if message arrived
263+
*/
95264
int canfd_read(can_t *obj, CANFD_Message *msg, int handle);
96265
#endif
97266

‎targets/TARGET_GigaDevice/TARGET_GD32F30X/can_api.c‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -410,7 +410,7 @@ void can_irq_set(can_t *obj, CanIrqType type, uint32_t enable)
410410
* 0 if write failed,
411411
* 1 if write was successful
412412
*/
413-
int can_write(can_t *obj, CAN_Message msg, int cc)
413+
int can_write(can_t *obj, CAN_Message msg)
414414
{
415415
can_trasnmit_message_struct transmit_message;
416416
uint32_t i;

‎targets/TARGET_GigaDevice/TARGET_GD32F4XX/can_api.c‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -411,7 +411,7 @@ void can_irq_set(can_t *obj, CanIrqType type, uint32_t enable)
411411
* 0 if write failed,
412412
* 1 if write was successful
413413
*/
414-
int can_write(can_t *obj, CAN_Message msg, int cc)
414+
int can_write(can_t *obj, CAN_Message msg)
415415
{
416416
can_trasnmit_message_struct transmit_message;
417417
uint32_t i;

‎targets/TARGET_NUVOTON/TARGET_M261/can_api.c‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -216,7 +216,7 @@ void can_irq_set(can_t *obj, CanIrqType irq, uint32_t enable)
216216

217217
}
218218

219-
int can_write(can_t *obj, CAN_Message msg, int cc)
219+
int can_write(can_t *obj, CAN_Message msg)
220220
{
221221
STR_CANMSG_T CMsg;
222222

@@ -226,7 +226,7 @@ int can_write(can_t *obj, CAN_Message msg, int cc)
226226
CMsg.DLC = msg.len;
227227
memcpy((void *)&CMsg.Data[0],(const void *)&msg.data[0], (unsigned int)8);
228228

229-
return CAN_Transmit((CAN_T *)NU_MODBASE(obj->can), cc, &CMsg);
229+
return CAN_Transmit((CAN_T *)NU_MODBASE(obj->can), 0, &CMsg);
230230
}
231231

232232
int can_read(can_t *obj, CAN_Message *msg, int handle)

‎targets/TARGET_NUVOTON/TARGET_M451/can_api.c‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -231,11 +231,8 @@ void can_irq_set(can_t *obj, CanIrqType irq, uint32_t enable)
231231

232232
}
233233

234-
int can_write(can_t *obj, CAN_Message msg, int cc)
234+
int can_write(can_t *obj, CAN_Message msg)
235235
{
236-
/* Unused */
237-
(void) cc;
238-
239236
STR_CANMSG_T CMsg;
240237

241238
CMsg.IdType = (uint32_t)msg.format;

‎targets/TARGET_NUVOTON/TARGET_M460/can_api.c‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -476,11 +476,8 @@ void can_irq_set(can_t *obj, CanIrqType irq, uint32_t enable)
476476
}
477477
}
478478

479-
int can_write(can_t *obj, CAN_Message msg, int cc)
479+
int can_write(can_t *obj, CAN_Message msg)
480480
{
481-
/* Unused */
482-
(void) cc;
483-
484481
const struct nu_modinit_s *modinit = get_modinit(obj->can, can_modinit_tab);
485482
MBED_ASSERT(modinit != NULL);
486483
MBED_ASSERT(modinit->modname == (int) obj->can);

‎targets/TARGET_NUVOTON/TARGET_M480/can_api.c‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -281,11 +281,8 @@ void can_irq_set(can_t *obj, CanIrqType irq, uint32_t enable)
281281

282282
}
283283

284-
int can_write(can_t *obj, CAN_Message msg, int cc)
284+
int can_write(can_t *obj, CAN_Message msg)
285285
{
286-
/* Unused */
287-
(void) cc;
288-
289286
STR_CANMSG_T CMsg;
290287

291288
CMsg.IdType = (uint32_t)msg.format;

‎targets/TARGET_NUVOTON/TARGET_NUC472/can_api.c‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -284,11 +284,8 @@ void can_irq_set(can_t *obj, CanIrqType irq, uint32_t enable)
284284

285285
}
286286

287-
int can_write(can_t *obj, CAN_Message msg, int cc)
287+
int can_write(can_t *obj, CAN_Message msg)
288288
{
289-
/* Unused */
290-
(void) cc;
291-
292289
STR_CANMSG_T CMsg;
293290

294291
CMsg.IdType = (uint32_t)msg.format;

‎targets/TARGET_NXP/TARGET_LPC176X/can_api.c‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -352,8 +352,9 @@ int can_frequency(can_t *obj, int f) {
352352
}
353353
}
354354

355-
int can_write(can_t *obj, CAN_Message msg, int cc) {
355+
int can_write(can_t *obj, CAN_Message msg) {
356356
unsigned int CANStatus;
357+
int cc = 0;
357358
CANMsg m;
358359

359360
can_enable(obj);

0 commit comments

Comments
 (0)