Service interface¶
Requirements defining the session layer’s service interface: the primitives exchanged with the application and with the transport, the parameters those primitives carry, and the mapping between them.
ISO 14229-2 describes the session layer as a service provider that the application calls. This crate is sans-io, so nothing is called: the caller supplies inputs and retrieves outputs. The requirements below keep the standard’s names for the primitives and state separately how each one is realised, so that the trace to the standard stays direct.
Throughout this document, the caller is the code that owns the session layer instance and drives it, typically the integration layer that also owns the transport. The application is the diagnostic application on whose behalf the session layer transmits and receives messages.
Requirements transcribed from ISO 14229-2 speak of the application passing a primitive to
the session layer, or the session layer passing one to the application, because that is how
the standard describes a service interface. Read those statements as fixing where a
primitive comes from and where it goes, not as describing a call: the caller supplies every
input on the application’s behalf and retrieves every output for it, as UDSS_LLR_0009
and UDSS_LLR_0011 require. ISO 14229-2’s service user is the application in this
document’s terms.
Sans-io binding¶
ISO 14229-2 does not contemplate a sans-io implementation, so these requirements are derived. They fix the boundary that every other requirement in this set is written against. The primitives they refer to are defined in Service primitives below.
Note the two senses of “input” and “output” in this document. UDSS_LLR_0001 uses I/O
in the operating-system sense, of reading and writing a device. UDSS_LLR_0009 and
UDSS_LLR_0011 use input and output in the state-machine sense, of values passed to
and retrieved from the session layer. The first is forbidden; the second is the whole
interface.
One assumption of use falls on the order in which the caller supplies inputs, and is
recorded in the qualification repository: a T_Data.conf is supplied before any
T_DataSOM.ind or T_Data.ind the transport received after the confirmed transmission
completed. A transport reports the two in that order, and a caller draining one queue
before the other is what the assumption forbids. A transmission completes here when the
transport can report it, and the assumption does not order a confirmation before an
indication of a message the transport received before then: ISO 14229-2:2021 10.3 lets the
client send its next request on complete reception of the response, which
ISO 14229-2:2021 9.2 REQ 5.19 does not exclude, so that request can be indicated before the
previous response is confirmed. UDSS_LLR_0088, UDSS_LLR_0093 and UDSS_LLR_0109
state what the server does with that overlap.
The session layer shall not open, read, or write a transport, socket, file, device, or operating system service. Rationale: the crate is sans-io. Every interaction with the vehicle network belongs to the caller, so one implementation serves CAN, DoIP, K-line and simulation alike. This requirement is verified by inspection of the crate’s own sources rather than by a runtime test; no black-box test can show that no I/O is performed. |
The crate shall compile under Rationale: a crate can perform no I/O of its own, as |
The crate shall declare no dependency that performs I/O. Rationale: |
The session layer shall allocate no memory. Rationale: the quantities this set keeps state for are properties of the deployment
rather than of the protocol — the number of a client’s channels, which |
The crate shall contain no Rationale: every claim this set makes about the session layer’s behaviour is a claim
about what safe Rust guarantees of the compiled crate, and one |
For every input the caller supplies, the session layer shall either process it or reject
it under Rationale: this is the global form of the argument |
The same sequence of inputs supplied from creation shall yield the same state and the
same outputs, in the same order, except where a requirement in this set leaves an order
unspecified. Rationale: this is what makes every requirement in the set testable without a network, a
clock or a scheduler — a property available because |
All state the session layer keeps shall live in the instance or in storage the caller supplies. The session layer shall retain nothing else between inputs. Rationale: |
Every input to the session layer shall be supplied by the caller. The session layer shall obtain information about the application and the transport by no other means. Creation of the instance precedes every input and is not one. Rationale: this excludes every source of state but an input the caller supplies — the session layer reading a clock itself, or consulting a global variable, would each be a second channel — which is what makes this crate sans-io: there is no way for state to reach the session layer except through the inputs the caller gives it. |
The inputs the caller supplies shall include Rationale: the enumeration is open because a list stated as exhaustive would be wrong
rather than merely incomplete should a document add an input; the acts are named in it
so that whether an act carries a timestamp is not left to inference, a reset delivered
at the instant a timer expires otherwise being read by one implementation as swallowing
the expiry’s indication and by another as following it. A timestamp may be supplied on
its own because a timer can expire while no message is exchanged, and |
Every output of the session layer shall be produced for the caller to retrieve. The session layer shall not invoke a callback, handler, or caller-supplied trait implementation in order to deliver an output. Rationale: a session layer that calls outwards is one whose behaviour depends on what the caller does while the session layer is part-way through a decision. Producing outputs for retrieval keeps their ordering explicit and makes reentrancy impossible. The prohibition on callbacks is verified by inspection of the crate’s public types, which take no caller-supplied trait object or function, rather than by a runtime test. |
The outputs the session layer produces for the caller to retrieve shall include
Rationale: the enumeration is open so that outputs the standard does not define, such
as the session-timeout indication required by |
The session layer shall not copy or retain the contents of Rationale: the crate is |
An output that refers to message data shall refer to data owned by the caller. Rationale: |
Where a requirement in this set requires the session layer to reject an input supplied
by the caller, the session layer shall report the rejection to the caller, shall produce
for the rejected input itself no output to the application and no output to the transport
layer, and shall leave its state as the expiries of the accompanying timestamp left it
under Rationale: requirements throughout this set refuse an input rather than react to it, and
without this requirement none would say what refusal means. A rejection cannot be
reported as an The expiries are excepted for the reason |
A rejection report shall state the cause of the rejection and, where the rejecting requirement states content for the report, that content; where several requirements reject the same input, the one report shall state every cause and carry the content each of them requires. Rationale: the report carries content because |
Timebase¶
The session layer’s whole notion of time is the caller’s. These requirements fix what a timestamp is and where it comes from; Timer model fixes what a timer does with one.
The session layer shall not read a clock. Every decision that depends on elapsed time shall be made from a timestamp supplied by the caller. Rationale: reading a clock is I/O by another name, and it makes timer behaviour untestable except in real time. A caller-supplied timestamp lets a test advance time arbitrarily, and lets each deployment choose the time source its platform provides. |
A timestamp shall be a 32-bit unsigned count of milliseconds. Rationale: the unit is milliseconds because that is the unit ISO 14229-2:2021 9.5
Table 5 states its timing parameter values in; |
The session layer shall compute the interval between two timestamps as their difference modulo 232, and shall treat that result as the elapsed time between them. Rationale: the subtraction is total, so no input can leave the session layer without a defined elapsed time, and modular subtraction returns the true interval for any interval shorter than the wrap, which every timeout in this set is by orders of magnitude. Whether the caller’s timestamps are non-decreasing is a property of the caller, recorded as an assumption of use in the qualification repository; a caller that supplies a decreasing timestamp obtains an interval close to the full range, which will expire timers early, and the session layer cannot distinguish that from a legitimate wrap. |
Every input shall be accompanied by a timestamp, which is the time at which the session layer treats that input as having occurred. A timestamp may also be supplied with no other input. Rationale: every timer requirement in this set starts, stops or expires a timer on an input, and an input with no time attached would have to be placed at the time of the last one, an interval the caller controls and the set does not state. A timestamp may be supplied on its own because a timer can expire while no message is exchanged. |
Service primitives¶
The session layer shall provide three service primitives to the application:
|
Low-Level Requirement: The session layer exchanges four protocol data units with the transport layer UDSS_LLR_0022
|
The session layer shall exchange the following protocol data units with the transport layer:
Each locator supplies a different part of this set. Clause 6.3 names |
Rationale: which parameters |
|
|
Low-Level Requirement: The caller identifies the channel of every inbound indication at a client UDSS_LLR_0026
|
At a client, every Rationale: the caller identifies the channel because the session layer cannot. A server answers the one client that asked, so every response it sends is physically addressed to the client whether the request that provoked it was physical or functional, an observation this set relies on rather than one the standard states; a response from one server may belong to the physical channel to that server or to a functional channel it was reached through, and nothing in the indication says which. The caller that issued the request knows. |
Low-Level Requirement: An indication naming no channel, or no existing one, is rejected UDSS_LLR_0027
|
An indication identifying a channel the client does not have, or identifying no channel
where Rationale: naming a channel that does not exist is a caller error, not an input, and so
is omitting the identifier |
Low-Level Requirement: The identified channel is not checked against the indication's addressing UDSS_LLR_0028
|
The session layer shall not verify the channel identified under Rationale: the channel named is trusted rather than checked because on a functional
channel the response’s addressing does not name the channel, and a check on a physical
channel alone would catch a misrouting only by coincidence; |
An instance of the session layer shall be created as a client or as a server, and its role shall not change thereafter. Rationale: every requirement in this set is stated for the client or for the server, and ISO 14229-2:2021 describes the two as distinct peer entities throughout clauses 6 to 10, each with its own timers in 9.6 Tables 7 and 8. Nothing in the set said how an instance came to be one or the other, so an implementer could build one instance that plays both roles and another that must be told, with the requirements silent on inputs that belong to the other role. A node that is both, a gateway or a tester under test, is two instances. The role is fixed at creation because no requirement gives a role change a meaning, and state held for one role has none in the other. |
A server shall reject, as
An interface in which a server cannot be handed a request classification to transmit, a response classification to receive, a channel identifier, the opening or withdrawal of a channel, a channel reset or a keep-alive release satisfies this requirement without a check. Rationale: the rejected inputs are listed rather than described, because “an input
whose form belongs to the other role” is not decidable for an |
A client shall reject, as
An interface in which a client cannot be handed a response classification to transmit, a request classification to receive, or a completion report satisfies this requirement without a check. Rationale: the rejected inputs are listed rather than described, because “an input
whose form belongs to the other role” is not decidable for an |
Creation of a server shall supply the association storage of Rationale: what creation supplies is gathered here because it was stated in four places and enumerated in none, and a tester building the first test must collect it. |
The session layer shall accept from the application an On |
The session layer shall deliver a received message to the application by an
|
On An interface that carries the data and the result as one value, in which the data is
present only where the result is The same shape serves the |
On Both outcomes produce an indication because |
The session layer shall confirm the completion of an |
The indication is used only within the session layer, to perform session layer timing.
The prohibition is on the |
On The application needs the confirmation in order to start actions that are executed immediately after transmission of a request or response message, such as an ECU reset or a bit rate change. |
The session layer shall provide for the setting of its protocol parameters by the caller. Clause 6.1 places the setting of protocol parameters in the service interface alongside transmission and reception. |
Low-Level Requirement: Every timing parameter is a 32-bit value in the timestamp's unit UDSS_LLR_0041
|
Every timing parameter that a requirement in this set conditions on, including the
Rationale: the width matches the timestamp’s because an interval is a modular difference of timestamps and a value beyond that range could never be reached. |
Low-Level Requirement: A parameter a timer loads has a fixed supply point and no default UDSS_LLR_0042
|
Every protocol parameter that a requirement loads a timer with shall be supplied with the instance it belongs to when that instance is created, with the caller-supplied storage it belongs to when that storage is created, or with the channel it belongs to when that channel is opened, and shall have no default. Rationale: no requirement in this set fixes a value for any timing parameter: the recommended and default values in ISO 14229-2:2021 9 are properties of a vehicle network and a deployment, not of this crate. That is also why a parameter has no default and is supplied at creation: a timer started before its parameter existed would have to be loaded with a value the set declines to choose. |
A protocol parameter may be set again at any time, and a change shall affect only a
timer set running after it; a timer already running keeps the value it was loaded
with, under Rationale: a caller correcting a parameter must not disturb a window a timer already
running holds a peer to. |
Message and peer identity¶
Two definitions the whole set depends on: which two addressing identities are the same peer, and how a multi-frame message’s start is matched to its completion.
A peer identity shall be formed by an address and, where Rationale: |
A Throughout this set, the first indication of a message is its Table 3 makes single-frame against multi-frame the transport’s distinction, and on a
functional channel the multi-frame responses of several servers may interleave, so
matching has to name the responder. The state this costs is stated with the client’s
requirements, in |
Parameter mapping¶
The validity of each session layer parameter in each service primitive shall be as
follows. The application layer column records the parameter each one corresponds to in
ISO 14229-2:2021 Table 1; the correspondence is by name and imposes nothing further on
this crate, to which the caller supplies Table 1’s validity columns are headed with the application layer’s
|
The session layer shall map the parameters of its protocol data unit onto the parameters of the transport layer protocol data unit, and the reverse, as follows.
|
Service primitive parameters¶
The requirements below constrain each parameter’s value set and width. ISO 14229-2:2021
8.2 defines the data types they are named in terms of: Enum is an 8-bit enumeration,
Unsigned Word a 16-bit unsigned value, Unsigned Long a 32-bit unsigned value, and
Byte Array a sequence of 8-bit aligned data. Where a requirement below gives a width,
that width is normative. Where it gives only a value set, as the enumerations do, the
in-memory representation is an implementation choice.
That is a deliberate departure from 8.2 for the three enumerated parameters,
UDSS_LLR_0048, UDSS_LLR_0049 and UDSS_LLR_0056. The clause makes Enum an
8-bit type; this crate neither encodes nor decodes those parameters on the wire, so their
width constrains nothing observable, and fixing it would forbid a Rust representation that
is safer and no larger. The value sets are transcribed exactly.
Low-Level Requirement: S_Mtype identifies the message type and the address information present UDSS_LLR_0048
|
Where |
|
|
|
|
|
On Rationale: the rejection is the set’s own, not clause 8.8’s, which defines the
parameter and says nothing of a mismatch. Without it |
|
ISO 14229-2:2021 does not enumerate the error values. Clause 8.10 states only that an
error value is issued when an error is detected by a lower layer, which is why this set
has the session layer carry such a value without interpreting it rather than act on its
meaning; that carrying is this set’s decision and is not stated by the clause. That
clause also requires the application layer entity to set the appropriate error bit where
two or more errors are discovered at once; that obligation falls on the application layer
and is not transcribed here, and no requirement in this set depends on |
Message classification¶
Several requirements in this set condition on what a message is rather than on its addressing alone. The session layer does not determine that by parsing. These requirements are derived: ISO 14229-2 states the conditions in terms of message content and leaves the means of recognising it to the implementation.
Rationale: several requirements condition on message content rather than on addressing
alone: on a message’s kind, on whether it selects a diagnostic session, on whether a
response was solicited, and on whether a request is a keep-alive or a repeat. Determining
those facts by parsing The classification is carried on |
Where a Rationale: |
Low-Level Requirement: The classification is associated with the transmission it describes UDSS_LLR_0059
|
The session layer shall associate the classification carried by an Rationale: the association is matched on addressing because that is the standard’s own
rule: ISO 14229-2:2021 7.6 has the The match is a declared widening of that list in one parameter: 7.6 identifies the
The storage is the caller’s because the number of peers an instance addresses is a
property of the deployment and the crate does not allocate, as The association with |
At most one association of Rationale: matching a confirmation on addressing alone, as The limit is survivable because each role has an exit, or an assumption in place of one.
An association whose |
An Rationale: this is what makes the limit of |
An Rationale: that storage is the caller’s and is sized by the deployment, so it can be exhausted by a caller addressing more peers than it provided for. |
A Rationale: no classification travels on a confirmation itself; it travels with the
association |
On initialisation no association of Rationale: an instance that began with an association outstanding would reject the first
|
A message classification shall consist of a kind and, where the message effects a transition to a diagnostic session, a session selection. The kind shall be one of:
A classification whose kind is A session selection shall state whether the session being selected is the default
session. It shall be present only where the message effects the transition: a request or
a positive response that selects a session carries one, and a negative response to a
session-change request does not. Which service carries the message is immaterial: a
DiagnosticSessionControl request or positive response is the usual carrier, and an
ECUReset positive response or the response to an OBD-range request that ISO 14229-1:2020
8.7.6 has abort the active service and start the default session carries one for the same
reason, the session layer being unable to tell the services apart under
Rationale: the definition of a final response is ISO 14229-2:2021 9.1.1’s; the requirement is derived because the classification, not the definition, is this set’s invention. The same clause settles a case the solicited and unsolicited split exists to carry: where a request schedules periodic responses, the initial response accepting or refusing the schedule is the final response, and the periodic transmissions that follow are not. The expected response count is stated by the client and has no server-side counterpart,
a server answering the one request in front of it. The The marker names the message’s purpose rather than the expiry that prompted it, because
two uses in the set lie outside the expiry: The Kind and session selection are separate because a positive response that selects a
session is at once a final response and a session selection. A session selection
accompanies requests as well as responses, because The selection states whether the session is the default one rather than naming the
session. Solicitation is separate from kind because a periodically transmitted positive response is at once a final response and unsolicited. It applies only to a final response because a response-pending message is by construction a reply to a request, so asking whether it was solicited has no meaning. A busy refusal is a kind of its own, not a solicited final response, because the request
it answers never became the service in progress. Addressing is how |
On Rationale: an exact number of zero is rejected rather than read as |
On Rationale: the |
Low-Level Requirement: A keep-alive with a session selection on a completion report is rejected UDSS_LLR_0068
|
On the completion report of Rationale: the |
Low-Level Requirement: A classification stating no kind where one is required is rejected UDSS_LLR_0069
|
A Rationale: no requirement in this set conditions on the kind of a message whose
reception failed and which was not addressed to a server: Every case this requirement reaches but one can be discharged by construction, by an
interface that makes the kind a required part of each indication obliged to state one.
Walked against each case in turn. A The case that remains is a client’s |
Low-Level Requirement: A request at a client stating no expected response count is rejected UDSS_LLR_0070
|
At a client, on Rationale: |
Low-Level Requirement: A final response stating neither solicited nor unsolicited is rejected UDSS_LLR_0071
|
A classification whose kind is Rationale: |
Low-Level Requirement: A classification or addressing not of the stated form is rejected UDSS_LLR_0072
|
A classification or addressing not of the form Rationale: the sentences of
No residual departure remains once |
The session layer shall not interpret the contents of Rationale: this is what makes The requirement is stated as an equivalence over pairs of inputs rather than as a
prohibition on reading, because the session layer must necessarily handle those bytes
in order to forward them: |
Low-Level Requirement: Completion of a request with no response is reported by the caller UDSS_LLR_0074
|
The session layer shall accept from the caller an input reporting that the handling of a received request is complete and that no response message will be transmitted. That input shall carry the addressing information of the request and the message classification that accompanied it. Rationale: ISO 14229-2:2021 9.5 Table 6 gives completion of the requested action, where
no response is required or allowed, as a condition that restarts The classification is carried on the input rather than recovered by correlating it with
an earlier |