doc/syscalls/20007_can.md
The CAN capsule allows the user to send and receive asynchronous messages on the CAN bus. The user must set the bitrate and operation mode of the peripheral before turning it on. After the device was enabled, the communication parameters cannot be modified without turning it off beforehand. The capsule can be controlled by the userspace using 10 different commands.
The userspace will be notified by the capsule when a message is sent and received and when the device was enabled and disabled. For the send command, there is a read-only shared buffer, and for the receive command, the kernel communicates with the userspace using a read-write buffer.
0Description: Does the driver exist?
Argument 1: unused
Argument 2: unused
Returns: Success if it exists, otherwise NODEVICE
1Description: Set the bitrate for the CAN peripheral. This will calculate all the timing parameters for the device. This command must be sent before enabling the device.
Argument 1: The bitrate value for the CAN communication.
Argument 2: unused
Returns: Ok(()) if the bitrate value is correct, otherwise INVAL if the value is_enabled incorrect or if the timing parameters could not be correctly calculated or BUSY if the device was previously enabled and is running.
2Description: Set the operation mode of the CAN peripheral. This command must be sent before enabling the device.
Argument 1: The operation mode that can be Loopback, Monitoring, Freeze or Normal.
Argument 2: unused
Returns: Ok(()) if the operaton value is correct, otherwise BUSY if the device was previously enabled and is running.
3Description: Enable the device. Previously, the bitrate and the operation mode must pe set.
Argument 1: unused
Argument 2: unused
Returns: Ok(()) if the enable process of the device worked, otherwise ALREADY if the device was previously enabled and is running, RESERVE if there is another application that is using the capsule or FAIL if the peripheral is in an error state/
Additional notes: After this command, the userspace must wait after 2 callbacks: the state_changed that sends
to the capsule the state of the device, and the enabled callback that confirms that the enable
process was successful.
4Description: Disable the device. Previously, the device must be enabled.
Argument 1: unused
Argument 2: unused
Returns: Ok(()) if the disable process of the device worked, otherwise BUSY if the device was already disabled or RESERVE if there is another application that is using the capsule.
Additional notes: After this command, the userspace must wait after 2 callbacks: the state_changed that sends
to the capsule the state of the device, and the disable callback that confirms that the disable
process was successful.
5Description: Send a message with a standard identifier. Previously, the device must be enabled.
Argument 1: the 16-bit identifier for the transmission.
Argument 2: the length of the message.
Returns: Ok(()) if the message could be sent, otherwise NOMEM if the message could not be accessed, RESERVE if there is another application that is using the capsule or OFF is the device is not enabled.
Additional notes: After this command, the userspace must wait after the transmit_complete callback that returns
to the capsule the buffer used for the data transfer between the driver and the capsule.
6Description: Send a message with an extended identifier. Previously, the device must be enabled.
Argument 1: the 32-bit identifier for the transmission.
Argument 2: the length of the message.
Returns: Ok(()) if the message could be sent, otherwise NOMEM if the message could not be accessed, RESERVE if there is another application that is using the capsule or OFF is the device is not enabled.
Additional notes: After this command, the userspace must wait after the transmit_complete callback that returns
to the capsule the buffer used for the data transfer between the driver and the capsule.
7Description: Sends to the driver the command to start listening for messages on the CAN bus. This will also configure filters so that any message can be received. Previously, the device must be enabled.
Argument 1: unused
Argument 2: unused
Returns: Ok(()) if the device is ready to receive messages, otherwise OFF is the device is not enabled, NOMEM if the buffer in which data should be saved cannot be accessed, SIZE if the buffer in which data should be saved cannot store more than 2 messages.
Additional notes: After this command, the userspace must wait after the message_received callback that returns
to the capsule a reference of the buffer used for the data transfer between the driver and the capsule.
The capsule must make a copy of the data because is does not own the buffer.
8Description: Sends to the driver the command to stop listening for messages on the CAN bus. This will also disable the filters that were previously enabled. Previously, the device must be enabled.
Argument 1: unused
Argument 2: unused
Returns: Ok(()) if the device was stopped from receiving messages, otherwise OFF is the device is not enabled, and FAIL if the buffer that was used to store messages cannot be owned by the capsule after begin owned by the driver.
Additional notes: After this command, the userspace must wait after the stopped callback that returns
to the capsule the buffer used for the data transfer between the driver and the capsule.
The capsule owns now the buffer.
9Description: Set the timing parameters for the CAN peripheral. This command must be sent before enabling the device.
Argument 1: An integer that has on each byte one timing parameter (as the parameters can be represented using 8 bits): time_segment1, time_segment2, synchronization_jump_width and the baud_rate_prescaler.
Argument 1 format:
```
0 8 16 24 32
+--------------+---------------+-----------------+---------------------+
|time_segment1 | time_segment2 | sync_jump_width | baud_rate_prescaler |
+--------------+---------------+-----------------+---------------------+
```
Argument 2: An integer that represents the propagation value for the communication.
Returns: Ok(()) if the parameters are correct, otherwise BUSY if the device was previously enabled and is running.
0Description: Buffer to write data from the peripheral to the user.
Buffer format:
0 1 2 3 4 5 6 7 10 11 ...
+---------+-----------+---------+--------+-----------+-----------+------------+------+-----------+ ...
| counter(u32) |buf0[0](u8)|buf0[1](u8)|buf0[2](u8) | .... |buf1[0](u8)| ...
+---------+-----------+---------+--------+-----------+-----------+------------+------+-----------+ ...
| Message 0 | Message 1 ...
0Description: Buffer to send data from the user to the peripheral. The length of the buffer is 8 bytes.
Buffer format:
0 1 2 3 7 8
+----------+----------+----------+--------+-----------+
|buf[0](u8)|buf[1](u8)|buf[2](u8)| .... |buf[7](u8) |
+----------+----------+----------+--------+-----------+
| Message |
0Description: Enable callback for when the device was enabled.
Argument 1: 0 if success, otherwise the error number if there is any error in the enable process
Argument 2: unused
Argument 3: unused
1Description: Disable callback for when the device was disabled.
Argument 1: 0 if success, otherwise the error number if there is any error in the disable process
Argument 2: unused
Argument 3: unused
2Description: Callback that the last message was sent.
Argument 1: 0 if success
Argument 2: unused
Argument 3: unused
3Description: Callback that a new message was received.
Argument 1: 0 if success
Argument 2: unused
Argument 3: unused
4Description: Callback that the receive process was stopped.
Argument 1: 0 if success
Argument 2: unused
Argument 3: unused
5Description: Callback that signals an error during the transmission or
receiving of a message or that a state_changed callback was called from
the driver without a previously sent enable or disable request or that the
state of the peripheral is different than the state the capsule expected it
to be.
Argument 1: the error code, that can be kernel errors or custom capsule errors: ERROR_TX or ERROR_RX
Argument 2: the kernel error code, if the first argument is a custom capsule error.
Argument 3: unused