Lely core libraries  2.3.4
can.h File Reference
#include <lely/ev/future.h>
#include <lely/ev/task.h>
#include <lely/io2/can/err.h>
#include <lely/io2/can/msg.h>
#include <lely/io2/dev.h>
#include <lely/libc/time.h>
Include dependency graph for can.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  io_can_chan_read_result
 The result of a CAN channel read operation. More...
 
struct  io_can_chan_read
 A CAN channel read operation. More...
 
struct  io_can_chan_write
 A CAN channel write operation. More...
 
struct  io_can_ctrl_vtbl
 
struct  io_can_chan_vtbl
 

Macros

#define IO_CAN_CHAN_READ_INIT(msg, err, tp, exec, func)
 The static initializer for io_can_chan_read.
 
#define IO_CAN_CHAN_WRITE_INIT(msg, exec, func)
 The static initializer for io_can_chan_write.
 

Typedefs

typedef const struct io_can_ctrl_vtbl *const io_can_ctrl_t
 An abstract CAN controller.
 
typedef const struct io_can_chan_vtbl *const io_can_chan_t
 An abstract CAN channel.
 

Enumerations

enum  io_can_bus_flag { IO_CAN_BUS_FLAG_ERR = 1u << 0, IO_CAN_BUS_FLAG_FDF = 1u << 1, IO_CAN_BUS_FLAG_BRS = 1u << 2 }
 The CAN bus flags. More...
 

Functions

int io_can_ctrl_stop (io_can_ctrl_t *ctrl)
 Stops a CAN controller. More...
 
int io_can_ctrl_stopped (const io_can_ctrl_t *ctrl)
 Returns 1 in the CAN controller is stopped, 0 if not, and -1 on error. More...
 
int io_can_ctrl_restart (io_can_ctrl_t *ctrl)
 (Re)starts a CAN contoller. More...
 
int io_can_ctrl_get_bitrate (const io_can_ctrl_t *ctrl, int *pnominal, int *pdata)
 Obtains the bitrate(s) of a CAN controller. More...
 
int io_can_ctrl_set_bitrate (io_can_ctrl_t *ctrl, int nominal, int data)
 Configures the bitrate(s) of a CAN controller. More...
 
int io_can_ctrl_get_state (const io_can_ctrl_t *ctrl)
 Returns the state of the CAN controller: one of CAN_STATE_ACTIVE, CAN_STATE_PASSIVE, CAN_STATE_BUSOFF, CAN_STATE_SLEEPING or CAN_STATE_STOPPED, or -1 on error. More...
 
static io_ctx_tio_can_chan_get_ctx (const io_can_chan_t *chan)
 
static ev_exec_tio_can_chan_get_exec (const io_can_chan_t *chan)
 
static size_t io_can_chan_cancel (io_can_chan_t *chan, struct ev_task *task)
 
static size_t io_can_chan_abort (io_can_chan_t *chan, struct ev_task *task)
 
io_dev_tio_can_chan_get_dev (const io_can_chan_t *chan)
 Returns a pointer to the abstract I/O device representing the CAN channel.
 
int io_can_chan_get_flags (const io_can_chan_t *chan)
 Returns the flafs of the CAN bus: any combination of IO_CAN_BUS_FLAG_ERR, IO_CAN_BUS_FLAG_FDF and IO_CAN_BUS_FLAG_BRS, or -1 on error. More...
 
int io_can_chan_read (io_can_chan_t *chan, struct can_msg *msg, struct can_err *err, struct timespec *tp, int timeout)
 Reads a CAN frame or CAN error frame from a CAN channel. More...
 
void io_can_chan_submit_read (io_can_chan_t *chan, struct io_can_chan_read *read)
 Submits a read operation to a CAN channel. More...
 
static size_t io_can_chan_cancel_read (io_can_chan_t *chan, struct io_can_chan_read *read)
 Cancels the specified CAN channel read operation if it is pending. More...
 
static size_t io_can_chan_abort_read (io_can_chan_t *chan, struct io_can_chan_read *read)
 Aborts the specified CAN channel read operation if it is pending. More...
 
ev_future_tio_can_chan_async_read (io_can_chan_t *chan, ev_exec_t *exec, struct can_msg *msg, struct can_err *err, struct timespec *tp, struct io_can_chan_read **pread)
 Submits an asynchronous read operation to a CAN channel and creates a future which becomes ready once the read operation completes (or is canceled). More...
 
int io_can_chan_write (io_can_chan_t *chan, const struct can_msg *msg, int timeout)
 Writes a CAN frame to a CAN channel. More...
 
void io_can_chan_submit_write (io_can_chan_t *chan, struct io_can_chan_write *write)
 Submits a write operation to a CAN channel. More...
 
static size_t io_can_chan_cancel_write (io_can_chan_t *chan, struct io_can_chan_write *write)
 Cancels the specified CAN channel write operation if it is pending. More...
 
static size_t io_can_chan_abort_write (io_can_chan_t *chan, struct io_can_chan_write *write)
 Aborts the specified CAN channel write operation if it is pending. More...
 
ev_future_tio_can_chan_async_write (io_can_chan_t *chan, ev_exec_t *exec, const struct can_msg *msg, struct io_can_chan_write **pwrite)
 Submits an asynchronous write operation to a CAN channel and creates a future which becomes ready once the write operation completes (or is canceled). More...
 
struct io_can_chan_readio_can_chan_read_from_task (struct ev_task *task)
 Obtains a pointer to a CAN channel read operation from a pointer to its completion task.
 
struct io_can_chan_writeio_can_chan_write_from_task (struct ev_task *task)
 Obtains a pointer to a CAN channel write operation from a pointer to its completion task.
 

Detailed Description

This header file is part of the I/O library; it contains the abstract CAN bus interface.

Author
J. S. Seldenthuis jseld.nosp@m.enth.nosp@m.uis@l.nosp@m.ely..nosp@m.com

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Definition in file can.h.

Enumeration Type Documentation

◆ io_can_bus_flag

The CAN bus flags.

Enumerator
IO_CAN_BUS_FLAG_ERR 

Reception of error frames is enabled.

IO_CAN_BUS_FLAG_FDF 

FD Format (formerly Extended Data Length) support is enabled.

IO_CAN_BUS_FLAG_BRS 

Bit Rate Switch support is enabled.

Definition at line 37 of file can.h.

Function Documentation

◆ io_can_ctrl_stop()

int io_can_ctrl_stop ( io_can_ctrl_t ctrl)
inline

Stops a CAN controller.

This terminates the transmission and reception of CAN frames. If the controller is already stopped, this function has no effect.

Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().
Postcondition
on success, io_can_ctrl_stopped() returns 1.

Definition at line 409 of file can.h.

◆ io_can_ctrl_stopped()

int io_can_ctrl_stopped ( const io_can_ctrl_t ctrl)
inline

Returns 1 in the CAN controller is stopped, 0 if not, and -1 on error.

In the latter case, the error number can be obtained with get_errc().

Definition at line 415 of file can.h.

◆ io_can_ctrl_restart()

int io_can_ctrl_restart ( io_can_ctrl_t ctrl)
inline

(Re)starts a CAN contoller.

Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().
Postcondition
on success, io_can_ctrl_stopped() returns 0.

Definition at line 421 of file can.h.

◆ io_can_ctrl_get_bitrate()

int io_can_ctrl_get_bitrate ( const io_can_ctrl_t ctrl,
int *  pnominal,
int *  pdata 
)
inline

Obtains the bitrate(s) of a CAN controller.

Parameters
ctrla pointer to a CAN controller.
pnominalthe address at which to store the nominal bitrate (can be NULL). For the CAN FD protocol, this is the bit rate of the arbitration phase.
pdatathe address at which to store the data bit rate (can be NULL). This bit rate is only defined for the CAN FD protocol; the value will be 0 otherwise.
Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().

Definition at line 427 of file can.h.

◆ io_can_ctrl_set_bitrate()

int io_can_ctrl_set_bitrate ( io_can_ctrl_t ctrl,
int  nominal,
int  data 
)
inline

Configures the bitrate(s) of a CAN controller.

Parameters
ctrla pointer to a CAN controller.
nominalthe nominal bitrate. For the CAN FD protocol, this is the bit rate of the arbitration phase.
datathe data bitrate. This bit rate is only defined for the CAN FD protocol; the value is ignored otherwise.
Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().
Postcondition
io_can_ctrl_stopped() returns 1.

Definition at line 433 of file can.h.

◆ io_can_ctrl_get_state()

int io_can_ctrl_get_state ( const io_can_ctrl_t ctrl)
inline

Returns the state of the CAN controller: one of CAN_STATE_ACTIVE, CAN_STATE_PASSIVE, CAN_STATE_BUSOFF, CAN_STATE_SLEEPING or CAN_STATE_STOPPED, or -1 on error.

In the latter case, the error number can be obtained with get_errc().

Definition at line 439 of file can.h.

◆ io_can_chan_get_ctx()

static io_ctx_t * io_can_chan_get_ctx ( const io_can_chan_t chan)
inlinestatic
See also
io_dev_get_ctx()

Definition at line 445 of file can.h.

◆ io_can_chan_get_exec()

static ev_exec_t * io_can_chan_get_exec ( const io_can_chan_t chan)
inlinestatic
See also
io_dev_get_exec()

Definition at line 451 of file can.h.

◆ io_can_chan_cancel()

static size_t io_can_chan_cancel ( io_can_chan_t chan,
struct ev_task task 
)
inlinestatic
See also
io_dev_cancel()

Definition at line 457 of file can.h.

◆ io_can_chan_abort()

static size_t io_can_chan_abort ( io_can_chan_t chan,
struct ev_task task 
)
inlinestatic
See also
io_dev_abort()

Definition at line 463 of file can.h.

◆ io_can_chan_get_flags()

int io_can_chan_get_flags ( const io_can_chan_t chan)
inline

Returns the flafs of the CAN bus: any combination of IO_CAN_BUS_FLAG_ERR, IO_CAN_BUS_FLAG_FDF and IO_CAN_BUS_FLAG_BRS, or -1 on error.

In the latter case, the error number can be obtained with get_errc().

Definition at line 475 of file can.h.

◆ io_can_chan_read()

int io_can_chan_read ( io_can_chan_t chan,
struct can_msg msg,
struct can_err err,
struct timespec *  tp,
int  timeout 
)
inline

Reads a CAN frame or CAN error frame from a CAN channel.

This function blocks until a frame is read, the timeout expires or an error occurs.

Parameters
chana pointer to a CAN channel.
msgthe address at which to store the CAN frame (can be NULL).
errthe address at which to store the CAN error frame (can be NULL).
tpthe address at which to store the system time at which the CAN frame or CAN error frame was received (can be NULL).
timeoutthe maximum number of milliseconds this function will block. If timeout is negative, this function will block indefinitely.
Returns
1 if a CAN frame is received, 0 if an error frame is received, or -1 on error. In the latter case, the error number can be obtained with get_errc().

Definition at line 481 of file can.h.

◆ io_can_chan_submit_read()

void io_can_chan_submit_read ( io_can_chan_t chan,
struct io_can_chan_read read 
)
inline

Submits a read operation to a CAN channel.

The completion task is submitted for execution once a CAN frame or error frame is received or a read error occurs.

Definition at line 488 of file can.h.

◆ io_can_chan_cancel_read()

static size_t io_can_chan_cancel_read ( io_can_chan_t chan,
struct io_can_chan_read read 
)
inlinestatic

Cancels the specified CAN channel read operation if it is pending.

The completion task is submitted for execution with result = -1 and errc = errnum2c(ERRNUM_CANCELED).

Returns
1 if the operation was canceled, and 0 if it was not pending.
See also
io_dev_cancel()

Definition at line 494 of file can.h.

◆ io_can_chan_abort_read()

static size_t io_can_chan_abort_read ( io_can_chan_t chan,
struct io_can_chan_read read 
)
inlinestatic

Aborts the specified CAN channel read operation if it is pending.

If aborted, the completion task is not submitted for execution.

Returns
1 if the operation was aborted, and 0 if it was not pending.
See also
io_dev_abort()

Definition at line 500 of file can.h.

◆ io_can_chan_async_read()

ev_future_t* io_can_chan_async_read ( io_can_chan_t chan,
ev_exec_t exec,
struct can_msg msg,
struct can_err err,
struct timespec *  tp,
struct io_can_chan_read **  pread 
)

Submits an asynchronous read operation to a CAN channel and creates a future which becomes ready once the read operation completes (or is canceled).

The result of the future has type io_can_chan_read_result.

Parameters
chana pointer to a CAN channel.
execa pointer to the executor used to execute the completion function of the read operation. If NULL, the default executor of the CAN channel is used.
msgthe address at which to store the CAN frame (can be NULL).
errthe address at which to store the CAN error frame (can be NULL).
tpthe address at which to store the system time at which the CAN frame or CAN error frame was received (can be NULL).
preadthe address at which to store a pointer to the read operation (can be NULL).
Returns
a pointer to a future, or NULL on error. In the latter case, the error number can be obtained with get_errc().

Definition at line 46 of file can.c.

◆ io_can_chan_write()

int io_can_chan_write ( io_can_chan_t chan,
const struct can_msg msg,
int  timeout 
)
inline

Writes a CAN frame to a CAN channel.

This function blocks until the frame is written, the timeout expires or an error occurs.

Parameters
chana pointer to a CAN channel.
msga pointer to the CAN frame to be written.
timeoutthe maximum number of milliseconds this function will block. If timeout is negative, this function will block indefinitely.
Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().

Definition at line 506 of file can.h.

◆ io_can_chan_submit_write()

void io_can_chan_submit_write ( io_can_chan_t chan,
struct io_can_chan_write write 
)
inline

Submits a write operation to a CAN channel.

The completion task is submitted for execution once the CAN frame is written or a write error occurs.

Definition at line 512 of file can.h.

◆ io_can_chan_cancel_write()

static size_t io_can_chan_cancel_write ( io_can_chan_t chan,
struct io_can_chan_write write 
)
inlinestatic

Cancels the specified CAN channel write operation if it is pending.

The completion task is submitted for execution with result = -1 and errc = errnum2c(ERRNUM_CANCELED).

Returns
1 if the operation was canceled, and 0 if it was not pending.
See also
io_dev_cancel()

Definition at line 518 of file can.h.

◆ io_can_chan_abort_write()

static size_t io_can_chan_abort_write ( io_can_chan_t chan,
struct io_can_chan_write write 
)
inlinestatic

Aborts the specified CAN channel write operation if it is pending.

If aborted, the completion task is not submitted for execution.

Returns
1 if the operation was aborted, and 0 if it was not pending.
See also
io_dev_abort()

Definition at line 524 of file can.h.

◆ io_can_chan_async_write()

ev_future_t* io_can_chan_async_write ( io_can_chan_t chan,
ev_exec_t exec,
const struct can_msg msg,
struct io_can_chan_write **  pwrite 
)

Submits an asynchronous write operation to a CAN channel and creates a future which becomes ready once the write operation completes (or is canceled).

The result of the future is an int containing the error number.

Parameters
chana pointer to a CAN channel.
execa pointer to the executor used to execute the completion function of the write operation. If NULL, the default executor of the CAN channel is used.
msga pointer to the CAN frame to be writen.
pwritethe address at which to store a pointer to the write operation (can be NULL).
Returns
a pointer to a future, or NULL on error. In the latter case, the error number can be obtained with get_errc().

Definition at line 70 of file can.c.