char.h header reference
[Devices support library module]

The source code of this header can be browsed online.

Description [link]

This class provides access to byte-stream oriented devices.

Two main types of operation are available on this driver: Byte buffer read and byte buffer write. Some variants operations exist as defined in enum dev_char_rq_type_e.

Example [link]

The following code reads 32 characters from a device, but accepts to get less if less data is available from the underlying hardware:

   struct device_char_s char_dev;

   // Lookup accessor for char_dev here...

   uint8_t data[32];
   struct dev_char_rq_s rq =
   {
       .type = DEV_CHAR_READ_PARTIAL,
       .data = data,
       .size = sizeof(data),
   };

   dev_char_rq_init(&rq, my_callback);

   DEVICE_OP(&char_dev, request, &rq);

Members [link]

Types [link]

typedef error_t (dev_char_cancel_t)(const struct device_char_s *accessor, struct dev_char_rq_s *rq)
typedef void (dev_char_request_t)(const struct device_char_s *accessor, struct dev_char_rq_s *rq)
struct dev_char_rq_s
enum dev_char_rq_type_e
struct device_char_s
struct driver_char_s

Functions [link]

void dev_char_rq_done(struct dev_char_rq_s *rq)
struct dev_char_rq_s * dev_char_rq_from_kr(struct kroutine_s *kr)
struct dev_char_rq_s * dev_char_rq_head(dev_request_queue_root_t *q)
void dev_char_rq_init(struct dev_char_rq_s *rq, kroutine_exec_t *exec)
void dev_char_rq_init_immediate(struct dev_char_rq_s *rq, kroutine_exec_t *exec)
void dev_char_rq_init_queue(struct dev_char_rq_s *rq, kroutine_exec_t *exec, struct kroutine_queue_s *queue)
void dev_char_rq_init_seq(struct dev_char_rq_s *rq, kroutine_exec_t *exec, struct kroutine_sequence_s *seq)
struct dev_char_rq_s * dev_char_rq_pop(dev_request_queue_root_t *q)
void dev_char_rq_pushback(dev_request_queue_root_t *q, struct dev_char_rq_s *rq)
void dev_char_rq_remove(dev_request_queue_root_t *q, struct dev_char_rq_s *rq)
struct dev_request_s * dev_char_rq_s_base(struct dev_char_rq_s *x)
struct dev_char_rq_s * dev_char_rq_s_cast(struct dev_request_s *x)
ssize_t dev_char_wait_op(const struct device_char_s *accessor, enum dev_char_rq_type_e type, uint8_t *data, size_t size)
error_t dev_char_wait_rq(const struct device_char_s *acc, struct dev_char_rq_s *rq)
struct device_accessor_s * device_char_s_base(struct device_char_s *x)
struct device_char_s * device_char_s_cast(struct device_accessor_s *x)

Macros [link]

Members detail [link]

#define DEV_CHAR_CANCEL(n) [link]

This macro is declared in device/class/char.h source file, line 212.

#define DEV_CHAR_REQUEST(n) [link]

This macro is declared in device/class/char.h source file, line 170.

#define DRIVER_CHAR_METHODS(prefix) [link]

This macro is declared in device/class/char.h source file, line 245.

#define __DEVICE_CHAR_H__ [link]

This macro is declared in device/class/char.h source file, line 61.

typedef error_t (dev_char_cancel_t)(const struct device_char_s accessor, struct dev_char_rq_s rq) [link]

This typedef is declared in device/class/char.h source file, line 238.

Char device class cancel() function type. Cancel a request.

This function cancels a request which have previously been passed to the dev_char_request_t function.

The function returns 0 if the request has been cancelled or -EBUSY if the request has already ended or will terminate very soon. It may also return -ENOTSUP. The request kroutine is not executed when this function returns 0.

When canceling a request of types DEV_CHAR_READ or DEV_CHAR_READ_FRAME, data which might have already been transferred will be lost.

When canceling a request of types @ref DEV_CHAR_WRITE or DEV_CHAR_WRITE_FRAME, some data might have been sent partially.

The size and data fields of a cancelled request have undefined values.

This declaration involves expansion of the DEV_CHAR_CANCEL macro.

typedef void (dev_char_request_t)(const struct device_char_s accessor, struct dev_char_rq_s rq) [link]

This typedef is declared in device/class/char.h source file, line 210.

Char device class request() function type. Enqueue a read or write request.

The type, data and size fields of the request must be initialized. The size can not be 0. The error field of the request is updated when the request completes.

When no error is reported, the data and size fields are updated in order to indicate what is left to transfer. These fields are left in an undefined state when an error is reported.

The following error codes are valid:

-ENOENT: The targeted sub-device does not exists. This is only reported when the driver implements sub-devices.
-ENOTSUP: The request operation is not supported by the device.
-EIO: Temporary or permanent hardware error.
-EPIPE: Data have been lost due to a buffer overflow or a sync error condition. This error is reported once.
-ENOSPC: The request date size is too small to store the incoming frame or the outgoing frame is to large to be processed by the device. This error is reported once.
-EBADDATA: The incoming data has been dropped due to a bad parity or bad checksum condition. This error is reported once.

The kroutine of the request may be executed from within this function. Please read Nested device request completion.

Parameter list:

dev: pointer to device descriptor
rq: pointer to request.

This declaration involves expansion of the DEV_CHAR_REQUEST macro.

void dev_char_rq_done(struct dev_char_rq_s *rq) [link]

This function is declared in device/class/char.h source file, line 168.

This function invokes or schedules execution of the char request callback associated to the request. For use in device drivers.

struct dev_char_rq_s * dev_char_rq_from_kr(struct kroutine_s *kr) [link]

This function is declared in device/class/char.h source file, line 168.

This function retrieves a pointer to the request when in the request completion callback routine.

struct dev_char_rq_s * dev_char_rq_head(dev_request_queue_root_t *q) [link]

This function is declared in device/class/char.h source file, line 168.

This function returns the oldest char request in the given queue. A NULL pointer is returned if the queue is empty. For use in device drivers.

void dev_char_rq_init(struct dev_char_rq_s rq, kroutine_exec_t exec) [link]

This function is declared in device/class/char.h source file, line 168.

This function initializes the given char request callback. This must be used before submitting the request to a driver.

This is available when CONFIG_MUTEK_KROUTINE_SCHED is defined.

void dev_char_rq_init_immediate(struct dev_char_rq_s rq, kroutine_exec_t exec) [link]

This function is declared in device/class/char.h source file, line 168.

This function initializes the given char request callback. This must be used before submitting the request to a driver.

void dev_char_rq_init_queue(struct dev_char_rq_s rq, kroutine_exec_t exec, struct kroutine_queue_s *queue) [link]

This function is declared in device/class/char.h source file, line 168.

This function initializes the given char request callback. This must be used before submitting the request to a driver.

This is available when CONFIG_MUTEK_KROUTINE_QUEUE is defined.

void dev_char_rq_init_seq(struct dev_char_rq_s rq, kroutine_exec_t exec, struct kroutine_sequence_s *seq) [link]

This function is declared in device/class/char.h source file, line 168.

This function initializes the given char request callback. This must be used before submitting the request to a driver.

This is available when CONFIG_MUTEK_KROUTINE_SCHED is defined.

struct dev_char_rq_s * dev_char_rq_pop(dev_request_queue_root_t *q) [link]

This function is declared in device/class/char.h source file, line 168.

This function removes and return the oldest char request in the queue. A NULL pointer is returned if the queue is empty. For use in device drivers.

void dev_char_rq_pushback(dev_request_queue_root_t q, struct dev_char_rq_s rq) [link]

This function is declared in device/class/char.h source file, line 168.

This function insert a new char request at the end of the given queue. For use in device drivers.

void dev_char_rq_remove(dev_request_queue_root_t q, struct dev_char_rq_s rq) [link]

This function is declared in device/class/char.h source file, line 168.

This function removes the specified char request from the queue. For use in device drivers.

struct dev_char_rq_s [link]

This struct is declared in device/class/char.h source file, line 149.

Field	Description
union <anonymous> {
struct dev_request_s base;
typeof(struct dev_request_s::error) error;
typeof(struct dev_request_s::pvdata) pvdata;
};
enum dev_char_rq_type_e type;	request type
uint8_t * data;	character buffer, updated by the driver to point to the next unprocessed character.
size_t size;	character buffer size, updated by the driver.

struct dev_request_s * dev_char_rq_s_base(struct dev_char_rq_s *x) [link]

This function is declared in device/class/char.h source file, line 168.

error code set by driver

struct dev_char_rq_s * dev_char_rq_s_cast(struct dev_request_s *x) [link]

This function is declared in device/class/char.h source file, line 168.

enum dev_char_rq_type_e [link]

This enum is declared in device/class/char.h source file, line 92.

this enum defines possible request types

Identifier	Description
DEV_CHAR_READ	Read data from the device. If no error occur, the request does not terminate until all data have been read.
DEV_CHAR_DISCARD	Read data from the device. If no error occur, the request does not terminate until all data have been read. The size field is updated but no data is stored.
DEV_CHAR_WRITE	Write data to the device. If no error occur, the request does not terminate until all data have been written.
DEV_CHAR_WRITE_FLUSH	This is equivalent to DEV_CHAR_WRITE, forcing flush of output data. On devices where data are always transmitted sent immediately, this is handled as a regular write.
DEV_CHAR_READ_PARTIAL	Read data from the device. If no error occur, the request does not terminate until at least one byte of data has been read.
DEV_CHAR_WRITE_PARTIAL	Write data to the device. If no error occur, the request does not terminate until at least one byte of data has been written.
DEV_CHAR_WRITE_PARTIAL_FLUSH	This is equivalent to DEV_CHAR_WRITE_PARTIAL, forcing flush of output data. On devices where data are always transmitted sent immediately, this is handled as a regular write.
DEV_CHAR_READ_NONBLOCK	Read data from the device. The request terminates immediately even if no data is currently available.
DEV_CHAR_WRITE_NONBLOCK	Write data to the device. The request terminates immediately even if no data can be written currently.
DEV_CHAR_WRITE_NONBLOCK_FLUSH	This is equivalent to DEV_CHAR_WRITE_NONBLOCK, forcing flush of output data.
DEV_CHAR_READ_POLL	This request terminates when the specified amount of data bytes is currently available from the device. The data field of the request is not used and the size field is not updated. Most device may not support this operation for size greater than 1.
DEV_CHAR_WRITE_POLL	This request terminates when the specified amount of data bytes may be written to the device without blocking. The data field of the request is not used and the size field is not updated. Most device may not support this operation for size greater than 1.
DEV_CHAR_READ_FRAME	Read a frame from the device. This operation is only supported by devices working with framed data. The returned data is guaranteed to match a frame start boundary. The returned frame data may be smaller than the request buffer.
DEV_CHAR_WRITE_FRAME	Write a frame to the device. This operation is only supported by devices working with framed data. The size of the request may be limited by the maximum frame size supported by the device.

ssize_t dev_char_wait_op(const struct device_char_s accessor, enum dev_char_rq_type_e type, uint8_t data, size_t size) [link]

This function is declared in device/class/char.h source file, line 268.

Blocking helper function. This function uses the scheduler api to put current context in wait state until the operation completes.

The return value is transferred size or -1 in case of error.

This is available when CONFIG_DEVICE_CHAR and CONFIG_MUTEK_CONTEXT_SCHED are both defined.

error_t dev_char_wait_rq(const struct device_char_s acc, struct dev_char_rq_s rq) [link]

This function is declared in device/class/char.h source file, line 253.

This function use the scheduler api to put current context in wait state during the request. This can only be called from a scheduler context.

This is available when CONFIG_MUTEK_CONTEXT_SCHED is defined.

struct device_char_s [link]

This struct is declared in DRIVER_CLASS_TYPES function like macro expansion, line 19 in device/class/char.h source file, line 243.

This struct is the device accessor object type for the char device class. This accessor must be initialized by calling the device_get_accessor function.

See also DRIVER_CLASS_CHAR, struct device_accessor_s and Device accessor.

Field	Description
union <anonymous> {
struct device_accessor_s base;
struct <anonymous> {
struct device_s * dev;
struct driver_char_s * api;
uint_fast8_t number;
};
};

struct device_accessor_s * device_char_s_base(struct device_char_s *x) [link]

This function is declared in DRIVER_CLASS_TYPES function like macro expansion, line 40 in device/class/char.h source file, line 243.

This function casts a char device accessor to a generic device accessor

struct device_char_s * device_char_s_cast(struct device_accessor_s *x) [link]

This function is declared in DRIVER_CLASS_TYPES function like macro expansion, line 33 in device/class/char.h source file, line 243.

This function casts a generic device accessor to a char device accessor

struct driver_char_s [link]

This struct is declared in DRIVER_CLASS_TYPES function like macro expansion, line 5 in device/class/char.h source file, line 243.

This struct is the driver API descriptor for the char device class.

See also DRIVER_CLASS_CHAR and struct driver_class_s.

Field	Description
uint16_t class_;
uint16_t ctx_offset;
dev_char_request_t * f_request;
dev_char_cancel_t * f_cancel;