trusty (3) driver_entry.3erl.gz
NAME
driver_entry - The driver-entry structure used by erlang drivers.
DESCRIPTION
Warning:
Use this functionality with extreme care!
A driver callback is executed as a direct extension of the native code of the VM. Execution is not made
in a safe environment. The VM can not provide the same services as provided when executing Erlang code,
such as preemptive scheduling or memory protection. If the driver callback function doesn't behave well,
the whole VM will misbehave.
* A driver callback that crash will crash the whole VM.
* An erroneously implemented driver callback might cause a VM internal state inconsistency which may
cause a crash of the VM, or miscellaneous misbehaviors of the VM at any point after the call to the
driver callback.
* A driver callback that do lengthy work before returning will degrade responsiveness of the VM, and
may cause miscellaneous strange behaviors. Such strange behaviors include, but are not limited to,
extreme memory usage, and bad load balancing between schedulers. Strange behaviors that might occur
due to lengthy work may also vary between OTP releases.
As of erts version 5.9 (OTP release R15B) the driver interface has been changed with larger types for the
callbacks output, control and call. See driver version management in erl_driver.
Note:
Old drivers (compiled with an erl_driver.h from an earlier erts version than 5.9) have to be updated and
have to use the extended interface (with version management ).
The driver_entry structure is a C struct that all erlang drivers define. It contains entry points for the
erlang driver that are called by the erlang emulator when erlang code accesses the driver.
The erl_driver driver API functions need a port handle that identifies the driver instance (and the port
in the emulator). This is only passed to the start function, but not to the other functions. The start
function returns a driver-defined handle that is passed to the other functions. A common practice is to
have the start function allocate some application-defined structure and stash the port handle in it, to
use it later with the driver API functions.
The driver call-back functions are called synchronously from the erlang emulator. If they take too long
before completing, they can cause timeouts in the emulator. Use the queue or asynchronous calls if
necessary, since the emulator must be responsive.
The driver structure contains the name of the driver and some 15 function pointers. These pointers are
called at different times by the emulator.
The only exported function from the driver is driver_init. This function returns the driver_entry
structure that points to the other functions in the driver. The driver_init function is declared with a
macro DRIVER_INIT(drivername). (This is because different OS's have different names for it.)
When writing a driver in C++, the driver entry should be of "C" linkage. One way to do this is to put
this line somewhere before the driver entry: extern "C" DRIVER_INIT(drivername);.
When the driver has passed the driver_entry over to the emulator, the driver is not allowed to modify the
driver_entry.
Note:
Do not declare the driver_entry const. This since the emulator needs to modify the handle, and the
handle2 fields. A statically allocated, and const declared driver_entry may be located in read only
memory which will cause the emulator to crash.
DATA TYPES
ErlDrvEntry :
typedef struct erl_drv_entry {
int (*init)(void); /* called at system start up for statically
linked drivers, and after loading for
dynamically loaded drivers */
#ifndef ERL_SYS_DRV
ErlDrvData (*start)(ErlDrvPort port, char *command);
/* called when open_port/2 is invoked.
return value -1 means failure. */
#else
ErlDrvData (*start)(ErlDrvPort port, char *command, SysDriverOpts* opts);
/* special options, only for system driver */
#endif
void (*stop)(ErlDrvData drv_data);
/* called when port is closed, and when the
emulator is halted. */
void (*output)(ErlDrvData drv_data, char *buf, ErlDrvSizeT len);
/* called when we have output from erlang to
the port */
void (*ready_input)(ErlDrvData drv_data, ErlDrvEvent event);
/* called when we have input from one of
the driver's handles */
void (*ready_output)(ErlDrvData drv_data, ErlDrvEvent event);
/* called when output is possible to one of
the driver's handles */
char *driver_name; /* name supplied as command
in open_port XXX ? */
void (*finish)(void); /* called before unloading the driver -
DYNAMIC DRIVERS ONLY */
void *handle; /* Reserved -- Used by emulator internally */
ErlDrvSSizeT (*control)(ErlDrvData drv_data, unsigned int command,
char *buf, ErlDrvSizeT len,
char **rbuf, ErlDrvSizeT rlen);
/* "ioctl" for drivers - invoked by
port_control/3 */
void (*timeout)(ErlDrvData drv_data); /* Handling of timeout in driver */
void (*outputv)(ErlDrvData drv_data, ErlIOVec *ev);
/* called when we have output from erlang
to the port */
void (*ready_async)(ErlDrvData drv_data, ErlDrvThreadData thread_data);
void (*flush)(ErlDrvData drv_data);
/* called when the port is about to be
closed, and there is data in the
driver queue that needs to be flushed
before 'stop' can be called */
ErlDrvSSizeT (*call)(ErlDrvData drv_data, unsigned int command,
char *buf, ErlDrvSizeT len,
char **rbuf, ErlDrvSizeT rlen, unsigned int *flags);
/* Works mostly like 'control', a synchronous
call into the driver. */
void (*event)(ErlDrvData drv_data, ErlDrvEvent event,
ErlDrvEventData event_data);
/* Called when an event selected by
driver_event() has occurred */
int extended_marker; /* ERL_DRV_EXTENDED_MARKER */
int major_version; /* ERL_DRV_EXTENDED_MAJOR_VERSION */
int minor_version; /* ERL_DRV_EXTENDED_MINOR_VERSION */
int driver_flags; /* ERL_DRV_FLAGs */
void *handle2; /* Reserved -- Used by emulator internally */
void (*process_exit)(ErlDrvData drv_data, ErlDrvMonitor *monitor);
/* Called when a process monitor fires */
void (*stop_select)(ErlDrvEvent event, void* reserved);
/* Called to close an event object */
} ErlDrvEntry;
int (*init)(void):
This is called directly after the driver has been loaded by erl_ddll:load_driver/2. (Actually when
the driver is added to the driver list.) The driver should return 0, or if the driver can't
initialize, -1.
ErlDrvData (*start)(ErlDrvPort port, char* command):
This is called when the driver is instantiated, when open_port/2 is called. The driver should
return a number >= 0 or a pointer, or if the driver can't be started, one of three error codes
should be returned:
ERL_DRV_ERROR_GENERAL - general error, no error code
ERL_DRV_ERROR_ERRNO - error with error code in erl_errno
ERL_DRV_ERROR_BADARG - error, badarg
If an error code is returned, the port isn't started.
void (*stop)(ErlDrvData drv_data):
This is called when the port is closed, with port_close/1 or Port ! {self(), close}. Note that
terminating the port owner process also closes the port. If drv_data is a pointer to memory
allocated in start, then stop is the place to deallocate that memory.
void (*output)(ErlDrvData drv_data, char *buf, ErlDrvSizeT len):
This is called when an erlang process has sent data to the port. The data is pointed to by buf, and
is len bytes. Data is sent to the port with Port ! {self(), {command, Data}}, or with
port_command/2. Depending on how the port was opened, it should be either a list of integers
0...255 or a binary. See open_port/3 and port_command/2.
void (*ready_input)(ErlDrvData drv_data, ErlDrvEvent event):
void (*ready_output)(ErlDrvData drv_data, ErlDrvEvent event):
This is called when a driver event (given in the event parameter) is signaled. This is used to help
asynchronous drivers "wake up" when something happens.
On unix the event is a pipe or socket handle (or something that the select system call
understands).
On Windows the event is an Event or Semaphore (or something that the WaitForMultipleObjects API
function understands). (Some trickery in the emulator allows more than the built-in limit of 64
Events to be used.)
To use this with threads and asynchronous routines, create a pipe on unix and an Event on Windows.
When the routine completes, write to the pipe (use SetEvent on Windows), this will make the
emulator call ready_input or ready_output.
Spurious events may happen. That is, calls to ready_input or ready_output even though no real
events are signaled. In reality it should be rare (and OS dependant), but a robust driver must
nevertheless be able to handle such cases.
char *driver_name:
This is the name of the driver, it must correspond to the atom used in open_port, and the name of
the driver library file (without the extension).
void (*finish)(void):
This function is called by the erl_ddll driver when the driver is unloaded. (It is only called in
dynamic drivers.)
The driver is only unloaded as a result of calling unload_driver/1, or when the emulator halts.
void *handle:
This field is reserved for the emulator's internal use. The emulator will modify this field;
therefore, it is important that the driver_entry isn't declared const.
ErlDrvSSizeT (*control)(ErlDrvData drv_data, unsigned int command, char *buf, ErlDrvSizeT len, char
**rbuf, ErlDrvSizeT rlen):
This is a special routine invoked with the erlang function port_control/3. It works a little like
an "ioctl" for erlang drivers. The data given to port_control/3 arrives in buf and len. The driver
may send data back, using *rbuf and rlen.
This is the fastest way of calling a driver and get a response. It won't make any context switch in
the erlang emulator, and requires no message passing. It is suitable for calling C function to get
faster execution, when erlang is too slow.
If the driver wants to return data, it should return it in rbuf. When control is called, *rbuf
points to a default buffer of rlen bytes, which can be used to return data. Data is returned
different depending on the port control flags (those that are set with set_port_control_flags).
If the flag is set to PORT_CONTROL_FLAG_BINARY, a binary will be returned. Small binaries can be
returned by writing the raw data into the default buffer. A binary can also be returned by setting
*rbuf to point to a binary allocated with driver_alloc_binary. This binary will be freed
automatically after control has returned. The driver can retain the binary for read only access
with driver_binary_inc_refc to be freed later with driver_free_binary. It is never allowed to alter
the binary after control has returned. If *rbuf is set to NULL, an empty list will be returned.
If the flag is set to 0, data is returned as a list of integers. Either use the default buffer or
set *rbuf to point to a larger buffer allocated with driver_alloc. The buffer will be freed
automatically after control has returned.
Using binaries is faster if more than a few bytes are returned.
The return value is the number of bytes returned in *rbuf.
void (*timeout)(ErlDrvData drv_data):
This function is called any time after the driver's timer reaches 0. The timer is activated with
driver_set_timer. There are no priorities or ordering among drivers, so if several drivers time out
at the same time, any one of them is called first.
void (*outputv)(ErlDrvData drv_data, ErlIOVec *ev):
This function is called whenever the port is written to. If it is NULL, the output function is
called instead. This function is faster than output, because it takes an ErlIOVec directly, which
requires no copying of the data. The port should be in binary mode, see open_port/2.
The ErlIOVec contains both a SysIOVec, suitable for writev, and one or more binaries. If these
binaries should be retained, when the driver returns from outputv, they can be queued (using
driver_enq_bin for instance), or if they are kept in a static or global variable, the reference
counter can be incremented.
void (*ready_async)(ErlDrvData drv_data, ErlDrvThreadData thread_data):
This function is called after an asynchronous call has completed. The asynchronous call is started
with driver_async. This function is called from the erlang emulator thread, as opposed to the
asynchronous function, which is called in some thread (if multithreading is enabled).
ErlDrvSSizeT (*call)(ErlDrvData drv_data, unsigned int command, char *buf, ErlDrvSizeT len, char
**rbuf, ErlDrvSizeT rlen, unsigned int *flags):
This function is called from erlang:port_call/3. It works a lot like the control call-back, but
uses the external term format for input and output.
command is an integer, obtained from the call from erlang (the second argument to
erlang:port_call/3).
buf and len provide the arguments to the call (the third argument to erlang:port_call/3). They can
be decoded using ei functions.
rbuf points to a return buffer, rlen bytes long. The return data should be a valid erlang term in
the external (binary) format. This is converted to an erlang term and returned by
erlang:port_call/3 to the caller. If more space than rlen bytes is needed to return data, *rbuf can
be set to memory allocated with driver_alloc. This memory will be freed automatically after call
has returned.
The return value is the number of bytes returned in *rbuf. If ERL_DRV_ERROR_GENERAL is returned (or
in fact, anything < 0), erlang:port_call/3 will throw a BAD_ARG.
void (*event)(ErlDrvData drv_data, ErlDrvEvent event, ErlDrvEventData event_data):
Intentionally left undocumented.
int extended_marker:
This field should either be equal to ERL_DRV_EXTENDED_MARKER or 0. An old driver (not aware of the
extended driver interface) should set this field to 0. If this field is equal to 0, all the fields
following this field also have to be 0, or NULL in case it is a pointer field.
int major_version:
This field should equal ERL_DRV_EXTENDED_MAJOR_VERSION if the extended_marker field equals
ERL_DRV_EXTENDED_MARKER.
int minor_version:
This field should equal ERL_DRV_EXTENDED_MINOR_VERSION if the extended_marker field equals
ERL_DRV_EXTENDED_MARKER.
int driver_flags:
This field is used to pass driver capability and other information to the runtime system. If the
extended_marker field equals ERL_DRV_EXTENDED_MARKER, it should contain 0 or driver flags
(ERL_DRV_FLAG_*) ored bitwise. Currently the following driver flags exist:
ERL_DRV_FLAG_USE_PORT_LOCKING:
The runtime system will use port level locking on all ports executing this driver instead of
driver level locking when the driver is run in a runtime system with SMP support. For more
information see the erl_driver documentation.
ERL_DRV_FLAG_SOFT_BUSY:
Marks that driver instances can handle being called in the output and/or outputv callbacks even
though a driver instance has marked itself as busy (see set_busy_port()). Since erts version
5.7.4 this flag is required for drivers used by the Erlang distribution (the behaviour has always
been required by drivers used by the distribution).
ERL_DRV_FLAG_NO_BUSY_MSGQ:
Disable busy port message queue functionality. For more information, see the documentation of the
erl_drv_busy_msgq_limits() function.
void *handle2:
This field is reserved for the emulator's internal use. The emulator will modify this field;
therefore, it is important that the driver_entry isn't declared const.
void (*process_exit)(ErlDrvData drv_data, ErlDrvMonitor *monitor):
This callback is called when a monitored process exits. The drv_data is the data associated with
the port for which the process is monitored (using driver_monitor_process) and the monitor
corresponds to the ErlDrvMonitor structure filled in when creating the monitor. The driver
interface function driver_get_monitored_process can be used to retrieve the process id of the
exiting process as an ErlDrvTermData.
void (*stop_select)(ErlDrvEvent event, void* reserved):
This function is called on behalf of driver_select when it is safe to close an event object.
A typical implementation on Unix is to do close((int)event).
Argument reserved is intended for future use and should be ignored.
In contrast to most of the other call-back functions, stop_select is called independent of any
port. No ErlDrvData argument is passed to the function. No driver lock or port lock is guaranteed
to be held. The port that called driver_select might even be closed at the time stop_select is
called. But it could also be the case that stop_select is called directly by driver_select.
It is not allowed to call any functions in the driver API from stop_select. This strict limitation
is due to the volatile context that stop_select may be called.
SEE ALSO
erl_driver(3erl), erl_ddll(3erl), erlang(3erl), kernel(3erl)