stm class: Update documentation to match the new identification rules

be used for trace sources with the id string of "user/dummy".

Trace sources have to open the stm class device's node and write their

trace data into its file descriptor. In order to identify themselves

to the policy, they need to do a STP_POLICY_ID_SET ioctl on this file

descriptor providing their id string. Otherwise, they will be

automatically allocated a master/channel pair upon first write to this

file descriptor according to the "default" rule of the policy, if such

exists.

trace data into its file descriptor.

In order to find an appropriate policy node for a given trace source,

several mechanisms can be used. First, a trace source can explicitly

identify itself by calling an STP_POLICY_ID_SET ioctl on the character

device's file descriptor, providing their id string, before they write

any data there. Secondly, if they chose not to perform the explicit

identification (because you may not want to patch existing software

to do this), they can just start writing the data, at which point the

stm core will try to find a policy node with the name matching the

task's name (e.g., "syslogd") and if one exists, it will be used.

Thirdly, if the task name can't be found among the policy nodes, the

catch-all entry "default" will be used, if it exists. This entry also

needs to be created and configured by the system administrator or

whatever tools are taking care of the policy configuration. Finally,

if all the above steps failed, the write() to an stm file descriptor

will return a error (EINVAL).

Previously, if no policy nodes were found for a trace source, the stm

class would silently fall back to allocating the first available

contiguous range of master/channels from the beginning of the device's

master/channel range. The new requirement for a policy node to exist

will help programmers and sysadmins identify gaps in configuration

and have better control over the un-identified sources.

Some STM devices may allow direct mapping of the channel mmio regions

to userspace for zero-copy writing. One mappable page (in terms of

there's a node in the root of the policy directory that matches the

stm_source device's name (for example, "console"), this node will be

used to allocate master and channel numbers. If there's no such policy

node, the stm core will pick the first contiguous chunk of channels

within the first available master. Note that the node must exist

before the stm_source device is connected to its stm device.

node, the stm core will use the catch-all entry "default", if one

exists. If neither policy nodes exist, the write() to stm_source_link

will return an error.

stm_console

===========