device/class/char.h header reference
[Devices support library module]

The source code of this header can be browsed online.

Description  

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.

See also DRIVER_CLASS_CHAR.

Example  

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  

Types  

Functions  

Macros  

Members detail  

#define DEV_CHAR_CANCEL(n)  

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

See also dev_char_cancel_t.

#define DEV_CHAR_REQUEST(n)  

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

See also dev_char_request_t.

#define DRIVER_CHAR_METHODS(prefix)  

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

See also struct driver_char_s.

#define __DEVICE_CHAR_H__  

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)   

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)   

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)  

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)  

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)  

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)  

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)  

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)  

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)  

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)  

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)  

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)  

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  

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

FieldDescription
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)  

error code set by driver

struct dev_char_rq_s * dev_char_rq_s_cast(struct dev_request_s *x)  

enum dev_char_rq_type_e  

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

this enum defines possible request types

IdentifierDescription
DEV_CHAR_READRead data from the device. If no error occur, the request does not terminate until all data have been read.
DEV_CHAR_DISCARDRead 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_WRITEWrite data to the device. If no error occur, the request does not terminate until all data have been written.
DEV_CHAR_WRITE_FLUSHThis 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_PARTIALRead 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_PARTIALWrite data to the device. If no error occur, the request does not terminate until at least on byte of data has been written.
DEV_CHAR_WRITE_PARTIAL_FLUSHThis 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_NONBLOCKRead data from the device. The request terminates immediately even if no data is currently available.
DEV_CHAR_WRITE_NONBLOCKWrite data to the device. The request terminates immediately even if no data can be written currently.
DEV_CHAR_WRITE_NONBLOCK_FLUSHThis is equivalent to DEV_CHAR_WRITE_NONBLOCK, forcing flush of output data.
DEV_CHAR_READ_POLLThis 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_POLLThis 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_FRAMERead 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_FRAMEWrite 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)  

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.

See also dev_char_wait_rq.

error_t dev_char_wait_rq(const struct device_char_s *acc, struct dev_char_rq_s *rq)  

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  

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.

FieldDescription
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)  

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)  

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  

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.

#define _DEV_CHAR_ALL  

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

mode

This macro is for internal use only.

#define _DEV_CHAR_FLUSH  

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

flush

This macro is for internal use only.

#define _DEV_CHAR_FRAME  

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

mode

This macro is for internal use only.

#define _DEV_CHAR_NONBLOCK  

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

mode

This macro is for internal use only.

#define _DEV_CHAR_PARTIAL  

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

mode

This macro is for internal use only.

#define _DEV_CHAR_POLL  

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

mode

This macro is for internal use only.

#define _DEV_CHAR_WRITE  

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

op

This macro is for internal use only.

Valid XHTML 1.0 StrictGenerated by diaxen on Wed Oct 17 21:18:37 2018 using MkDoc